FTPQ SCRIPT IBM (CMS) as an FTP 'Q' end This file describes the FTP parameters that must be passed to the IBM (CMS) FTP when using it as a 'Q' end. It is available as a HELP file (named FTPQ) and as a SCRIPT file. Included is a description of how to retrieve output from jobs run in any of the IBM batch systems. Strictly speaking, output retrieval is an automated 'P' end function, but the full details are given here as these facilities will typically be needed in conjunction with jobs which have been input via the Q-end FTP. There is a separate HELP file for normal 'P' end usage. This can be invoked by inputting 'HELP FTP'. FTP parameters are referred to here by standardised names such as . These should be self-explanatory, and are as far as possible the same as those used in the documentation for other SERCnet 'Q' end implementations. PARAMETERS : Two contexts should be distinguished: 'CMS' context and 'Jobs' context. The 'Jobs' context applies if, and only if, the Access mode parameter, , is Take Job Input or Take Job Output. (1) 'CMS' Context. The parameter takes the following general form: [CMS/] userid [/[rpass] [/diskad]] Items in square brackets are optional. The only component always essential is therefore a userid acceptable to CMS. If a file is being fetched from CMS, the appropriate read- password (rpass) may be quoted either here or in the separate parameter. If a file is to be fetched from a minidisk other than the 'A' disk (address 191), the disk address (diskad) must be given. Default values for rpass and diskad are ALL and 191 respectively. If a read-password is supplied in the parameter it overrides any read-password given in . (2) 'Jobs' Context. With Take Job Input, should be FEM or null or absent if the job is to be sent to the MVT batch system at RAL. If it is to be sent to a batch system CMS Q-END FTP (APRIL 1983) PAGE 1 FTPQ SCRIPT accessible via VNET, should contain VNET/node/JOB (e.g: VNET/GEN/JOB if the destination is CERN). With Take Job Output, must contain a valid CMS userid if the file is to appear on an RAL printer. This is to facilitate pigeon-holing. If the file is to be sent to a VNET destination, must contain VNET/node[/tag]. Square brackets, as usual denote optional fields. The tag information may be anything meaningful to VNET. Examples of valid parameters: BLOGGS CMS/BLOGGS BLOGGS//192 BLOGGS /QWERT / 193 FEM VNET/GEN/JOB VNET/RLR26 : In 'CMS' context, a valid CMS file id is required. It comprises a filename, a filetype, and optionally a filemode. The filemode is ignored for an incoming file. The filename, filetype and filemode may be separated by single dots instead of by spaces if desired (this is for the convenience of the P-end, which may not allow spaces within a parameter). In 'Jobs' context (i.e: if the access mode is Take Job Output or Take Job Input), a file id need not be given, in which case the file is provided with a standard filename of FTPFILE. If a file id is given, only the filename part of it is needed or used. A filetype of LISTING or JOB is always provided by the software. If an incoming file is to be stored in a CMS file of filetype LISTING, paper-feed control characters should be present in the file and the parameter must specify ANSI- type paper-feed control. If the destination is a printer, default carriage control characters will be supplied if necessary. : This parameter is needed when fetching a file from CMS if the read-password has not been specified in the parameter. A CMS Q-END FTP (APRIL 1983) PAGE 2 FTPQ SCRIPT read-password given here takes precedence over any read-password specified in the parameter. This parameter need not be supplied when sending a file. : Ignored : Ignored : Ignored : The following access modes are accepted: Read only Make only Replace only Append only Make or Replace Make or Append Take Job Output Take Job Input The modes Make only, Replace only, Append only, Make or Replace, and Make or Append are treated as equivalent, as there is no direct access to user files for writing. Incoming files are spooled to the reader of the appropriate virtual machine, and the user must read them into CMS files using the RECEIVE, DISK LOAD or YDISK LOAD commands. It should be noted that DISK LOAD will write the file to the 'A' disk (the filemode quoted is not used), using the file's own filename and filetype. This will overwrite any existing file with the same id. YDISK LOAD allows the user to store the file with a file id of his own choosing. Take Job Output causes the file to be spooled to a VM printer at RAL, or to a device on a VNET node. Take Job Input causes it to be spooled to the MVT batch virtual machine or to a jobmill accessible via VNET. : No limit is imposed for files being fetched from the IBM. For incoming files, the 'transmission limit' parameter will be negotiated to a maximum of 8 megabytes, and exceeding this limit will then be treated as a protocol violation. : The maximum record size is 252 bytes, except for printer or LISTING files in which case it is 133 bytes including carriage control, and for job input files in which case it is 80 CMS Q-END FTP (APRIL 1983) PAGE 3 FTPQ SCRIPT bytes. Records in job input files are padded to 80 bytes with trailing blanks if necessary. : EBCDIC (Blue Book version), ASCII (IA5) and BINARY are supported as transfer codes (in that order of preference). Files are assumed to be stored in CMS in EBCDIC (RAL version) unless BINARY is used, in which case no assumptions are made and no code conversions are applied. : Except with =POST, this parameter is defined as meaningful with Take Job Output only. 'Devices' available are: LP : Line printer. must contain a valid userid (to facilitate pigeon-holing), or have the form defined for use with VNET. If is given, this is used in constructing a document name with a filetype of LISTING. If is not supplied, the document name used is FTPFILE LISTING. POST : Postbox. The file is spooled to 's virtual reader with a filetype of MAIL. : Binary word size of 8 bits is assumed and is not negotiable. : ANSI paper-feed control must be specified for files destined for a CMS file of filetype LISTING. : The site mnemonic of the IBM (CMS) Q-end is RLIB. NOTES a) Unless the file transferred is a mail file or a job, a special mail file is sent to the virtual machine quoted in , informing the user of the transfer that has taken place. This may be read most conveniently using XRDR if it is at the top of the reader queue. b) As there is no write access to user CMS files by FTP, all incoming files for CMS are spooled to the appropriate virtual machine reader in DISK DUMP/LOAD format. JOB OUTPUT RETRIEVAL FACILITIES CMS Q-END FTP (APRIL 1983) PAGE 4 FTPQ SCRIPT The printer output from any job run in the MVT batch system or a batch system accessible via VNET may be routed via FTP80 (not FTP77) to any network destination. The access mode used is Take Job Output if the destination is a device, or 'Replace or Make' if it is a file. If the job was not input via the CMS 'Q' end FTP, it must contain a /*ROUTE PRINT NIFTP card if its output is to be routed via FTP. If it was input via the CMS 'Q' end FTP, the output will automatically return to NIFTP for disposal. In either case, the JCL of the job must contain a //* card with *FILE and at least one parameter containing a network address or mnemonic, and possibly other parameters required by the remote 'Q' end implementation. IMPORTANT NOTE: It is essential NOT to specify MSGLEVEL=0 or MSGLEVEL=(0,...) in the JOB card, as this will cause the JCL, including the *FILE cards, to be discarded before NIFTP receives the output. The format of the *FILE card is a series of Keyword=value fields separated by commas. The allowed keywords are defined below and must not contain blanks. If a value needs to contain blanks, commas or (single) quotes, the value as a whole should be enclosed in (single) quotes. Quotes within the quotes must be doubled. Elsewhere, blanks are ignored. More than one *FILE card may be used, but if so they must be adjacent and a parameter must not overflow from one card to the next. If output routing is not possible because of an erroneous or absent *FILE card or for other non-recoverable reason, the job will be printed on the central IBM printer with the distribution code set equal to the batch job name, and where possible a message on the banner page indicating the reason. If output routing fails because of some apparently transitory situation, such as a network fault or remote host not active, it will be held and retried at intervals according to the normal P-end re-try strategy. There is no way of cancelling or re-routing such 'held' jobs. To allow this would require additional authorisation procedures. Punch output may also be routed via FTP if the user's program causes the punch stream to start with the necessary //* *FILE card(s). If a punch file cannot be delivered, for a non-recoverable reason, it will be thrown away. The defined keywords are as follows:- SITE : A network address or mnemonic (mandatory). USER : This is sent in the FTP 'username' parameter (optional unless required by destination). CMS Q-END FTP (APRIL 1983) PAGE 5 FTPQ SCRIPT PSWD : Sent in the 'user password' parameter (optional unless required by destination). DEV : If the output is to go to a real device, the 'output device type' parameter is set from this value. The default is LP. If DEV=FILE is specified, the file is sent with an access mode of 'Replace or Make' instead of 'Take Job Output'. In that case the FILE parameter can contain the destination file name. FILE : Optional. The default is the job name, and this may be used by the remote system to construct a banner heading. If DEV=FILE is specified, this parameter should convey a file name for use by the destination system. QUAL : If a value for this is specified, it will be sent in the 'device qualifier' parameter. TRANSP : If TRANSP=YES is specified, print-stream output will be sent transparently. The default is TRANSP=NO, which protects remote devices from garbage in the data stream by translating control characters to nulls. MAIL : A CMS userid may be specified, in which case the NIFTP logging file associated with the transfer will be routed to the virtual machine indicated. If this parameter is not specified, the logging file will be discarded. EXAMPLE of parameters specified on two adjacent cards: //* *FILE SITE=RLGB , USER=DEMO, PSWD='ABC DEF' //* *FILE DEV=FILE, FILE=.TESTFILE CMS Q-END FTP (APRIL 1983) PAGE 6