IBM Sterling Connect CEz OSRemote_User_Guide OSRemote User Guide
User Manual: CEzOSRemote_User_Guide user guide pdf - FTP File Search (14/20)
Open the PDF directly: View PDF .
Page Count: 98
Download | |
Open PDF In Browser | View PDF |
IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Version 1.5 This edition applies to the 1.5 Version of IBM® Sterling Connect:Enterprise® for z/OS® and to all subsequent releases and modifications until otherwise indicated in new editions. Before using this information and the product it supports, read the information in Notices on page 91. Licensed Materials - Property of IBM IBM® Sterling Connect:Enterprise® for z/OS® © Copyright IBM Corp. 2000, 2011. All Rights Reserved. US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp. CEzOSRUG1107 Contents Chapter 1 Sterling Connect:Enterprise FTP Implementation Data Representation and Storage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ASCII . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EBCDIC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Format Control for Character Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Record . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Transfer Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Compressed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling FTP Connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implementing Firewall Navigation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implementing the Clear Control Channel (CCC) Feature . . . . . . . . . . . . . . . . . . Connecting to a Sterling Connect:Enterprise FTP Server . . . . . . . . . . . . . . . . . . . . . Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Log On . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sterling Connect:Enterprise FTP Server and Equivalent Client Commands . . . . . . . SITE Command Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample Output of STATUS Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . VSAM Batch Status Flags. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Different DIRFORM Layouts Returned by LIST . . . . . . . . . . . . . . . . . . . . . . . . . Sterling Connect:Enterprise Variations from Standard FTP Commands. . . . . . . . . . User Batch ID Syntax and Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . delete or mdelete Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sterling Connect:Enterprise FTP del, delete, and mdelete Command Syntax Batch Selection with Sterling Connect:Enterprise FTP del Command . . . . . dir Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sterling Connect:Enterprise FTP dir Command Syntax . . . . . . . . . . . . . . . . Batch Selection with Sterling Connect:Enterprise FTP dir Command . . . . . get or mget Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sterling Connect:Enterprise FTP get Syntax . . . . . . . . . . . . . . . . . . . . . . . . Batch Selection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Batch Transmission . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Batch Status Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 7 7 8 8 8 9 9 10 10 11 11 11 11 11 12 13 13 14 14 14 14 15 19 28 30 31 35 35 37 37 37 38 39 39 39 40 40 41 41 3 Contents put or mput Command (STOR) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sterling Connect:Enterprise FTP put Syntax . . . . . . . . . . . . . . . . . . . . . . . . put or mput Command (STOU) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sterling Connect:Enterprise FTP put Syntax . . . . . . . . . . . . . . . . . . . . . . . . pwd Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . pwd Command Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . cd Command. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . NLST Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sterling Connect:Enterprise NLST Command Syntax . . . . . . . . . . . . . . . . . Batch Selection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Preparing Batches for the Sterling Connect:Enterprise FTP Server . . . . . . . . . . . . . Using $$Commands and /*Cards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . $$Commands and /*SIGNON with /*BINASC. . . . . . . . . . . . . . . . . . . . . . . . $$Commands and /*SIGNON without /*BINASC . . . . . . . . . . . . . . . . . . . . . Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . $$ADD Command Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 2 Communicating with SNA Sites Start and End a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Using Sterling Connect:Enterprise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Wildcard Characters in Sterling Connect:Enterprise Names . . . . . . . . . . . . . . . . . . . Terminal-Dependent Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNA Sites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . MLU (Multiple Logical Unit) Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Device Media Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Console Display Use. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Data Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Batch Separation Using FMHs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNA Transparency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Disconnect Interval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . EBCDIC Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample Data Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNA Site Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 3 Communicating with BSC Sites Start and End a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sterling Connect:Enterprise Support for Signon (BSC Sites) . . . . . . . . . . . . . . . Host-Initiated Communications (Auto Connect) . . . . . . . . . . . . . . . . . . . . . . . . . Using Sterling Connect:Enterprise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Wildcard Characters in Sterling Connect:Enterprise Names . . . . . . . . . . . . . . . . . . . Terminal-Dependent Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BSC Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Free-Form BSC SIGNON . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Blank Compression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Blank Truncation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Blocked Data Records . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 42 42 43 44 44 44 44 45 46 46 47 48 48 49 49 49 51 51 52 52 53 54 54 54 55 55 56 56 57 57 57 58 65 65 65 66 66 67 67 68 68 68 69 69 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Contents BSC Transparency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Record Separator Override . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Use of $TURNLINE$. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Temporary Text Delay (TTD) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . WAIT Acknowledgement (WACK). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Sample Data Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . BSC Site Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 4 Remote User Commands Submit Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . $$ADD Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . $$ADD Defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Multiple Batches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . $$DELETE Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . $$DIRECTORY Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNA Logon System Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . SNA LOGOFF and $$LOGOFF System Functions . . . . . . . . . . . . . . . . . . . . . . . . . . Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . $$REQUEST Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Parameter Interrelationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . $$REQUEST Sample Outputs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 5 Error Messages Remote User Error Messages (*** ERROR ***) . . . . . . . . . . . . . . . . . . . . . . . . . . . . Notices 69 69 70 70 70 70 71 73 73 76 76 77 77 77 78 78 78 78 78 79 79 81 81 81 82 82 82 82 83 83 83 83 85 85 91 Trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Index IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 93 95 5 Contents 6 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Chapter 1 Sterling Connect:Enterprise FTP Implementation The IBM® Sterling Connect:Enterprise® for z/OS® FTP feature provides the standard FTP interface to an FTP client. It operates as an FTP server for connections from remote FTP clients. Sterling Connect:Enterprise places restrictions on the use and meaning of some FTP commands, which are discussed in this chapter. In addition, remote users can embed $$ADD commands in an FTP data stream to add data to the host data repository on the Sterling Connect:Enterprise FTP server. The last section in this chapter deals with using the $$ADD command and how data files must be formatted in order for the Sterling Connect:Enterprise FTP server to properly scan and interpret the $$ADD command including the data. Data Representation and Storage Transferring files between different computer systems introduces a myriad of issues emanating from the differences between computer systems. The IBM System z/OS architecture uses an 8-bit EBCDIC byte to represent character data. The IBM PS/2 system uses an 8-bit ASCII byte to represent character data. Some computers use a 7-bit ASCII code. The IBM PS/2 system organizes files as a continuous stream of data. The IBM System z/OS organizes files into records. With all these differences, Sterling Connect:Enterprise must provide a method of transferring these files and making them available for use on the receiving system. The Sterling Connect:Enterprise FTP feature deals with these issues. FTP provides for FTP client and FTP server implementations to negotiate the data representation and storage types through the use of the data type, data structure, and transmission mode standard specifications. Note: You are responsible for specifying the Sterling Connect:Enterprise FTP server options and the remote FTP client options so that the data transferred is usable by the receiving host. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 7 Chapter 1 Sterling Connect:Enterprise FTP Implementation Data storage attributes are determined by the host system. The Sterling Connect:Enterprise FTP feature stores character data in EBCDIC and image (binary) data as received. Data received as NVT-ASCII is converted to EBCDIC before being added to the current working data repository. Sterling Connect:Enterprise performs the role of FTP server and the types are set by the remote FTP client. The Sterling Connect:Enterprise FTP feature transfers data as 8-bit bytes. If your remote FTP client uses a different byte length, it is up to you to implement the appropriate conversion between local byte size and the Sterling Connect:Enterprise FTP feature 8-bit byte transfer length. Data Type Data type specifies how the receiver interprets the data bits being transferred. The receiver is either the Sterling Connect:Enterprise FTP server or the remote FTP client. Sterling Connect:Enterprise FTP server assumes that the remote FTP client uses the ASCII character set. If the remote site does not use the ASCII character set, the remote FTP client must send the TYPE command to change the data type to EBCDIC or BINARY. The FTP standard includes four data types: ASCII, EBCDIC, image, and local. Sterling Connect:Enterprise FTP server provides the ability to specify three data types: ASCII, EBCDIC, and image. The local byte size is 8 bits (L 8) for Sterling Connect:Enterprise, and cannot be changed. ASCII ASCII is character data. The sender converts the data from its internal representation into standard 8-bit NVT-ASCII before sending the data. Each line of data ends with a carriage-return-line-feed (). An ASCII is hexadecimal '0D0A'. If Sterling Connect:Enterprise is receiving, the data is translated from NVT-ASCII to EBCDIC and the sequences are replaced with a new line ( ) character before the data is added to the current data repository. An EBCDIC is hexadecimal '15'. If Sterling Connect:Enterprise is sending, the data is translated from EBCDIC into NVT-ASCII and the characters are replaced with the characters before transmitting the data to the remote FTP server. ASCII (TYPE A) is the default data type for Sterling Connect:Enterprise FTP feature. EBCDIC EBCDIC is character data. The EBCDIC data type is the most efficient way to transfer data between EBCDIC hosts. If Sterling Connect:Enterprise is receiving, the data is not translated before being added to the current data repository. If Sterling Connect:Enterprise is sending, the data is not translated before being transmitted. Not all remote ASCII hosts accept data type EBCDIC. Some remote FTP servers reject data type EBCDIC. Some hosts accept data type EBCDIC and store it as binary. Other hosts accept data type EBCDIC as binary, and then translate the data into data type ASCII. 8 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Data Representation and Storage Format Control for Character Data Data types ASCII and EBCDIC have a second, optional parameter called format control. The format control parameter specifies the presence and type of vertical formatting control in the data being transferred. The Sterling Connect:Enterprise FTP implementation ignores ASCII and EBCDIC format controls. The following table shows the data types accepted by Sterling Connect:Enterprise FTP and the TELNET codes associated with the data types. Type Description A ASCII nonprint See Note 1. AC ASCII nonprint See Note 1. AN ASCII nonprint See Note 1. AT ASCII telnet See Note 1. E EBCDIC nonprint See Note 2. EC EBCDIC nonprint See Note 2. EN EBCDIC nonprint See Note 2. ET EBCDIC telnet See Note 2. I Image (binary) 1 Data types A, A C, A N, and A T are identical in the Sterling Connect:Enterprise FTP implementation. 2 Data types E, EC, E N, and E T are identical in the Sterling Connect:Enterprise FTP implementation. Image Image is noncharacter data. Data is sent and received as contiguous bits packed into 8-bit bytes. No translation takes place by Sterling Connect:Enterprise. Sterling Connect:Enterprise also assumes that no translation takes place at the remote FTP server. Character data can be transmitted as image, but no translation occurs. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 9 Chapter 1 Sterling Connect:Enterprise FTP Implementation Term Definition CC Indicates that data contains ASA control characters in the first position of every line. The first character determines the vertical movement of the paper before the data is printed. The ASA control character is not printed. The first character after the ASA control character is printed on the first position of the output line on the paper. NONPRINT Indicates the data does not include format control characters. Nonprint format control is generally accepted by all FTP implementations. This format can be used for data destined for storage or processing. A print processor can assume that nonprint data contains standard values for spacing and margins. TELNET The file contains ASCII or EBCDIC vertical format controls that a printer Process can interpret. Some examples of TELNET vertical form control are carriage return ( ), line feed ( ), new line ( ), and vertical tab ( ). The sequence denotes end-of-line, not vertical control. The four standard ASA control characters are: Character Vertical Spacing blank Move paper up one line. 0 Move paper up two lines. 1 Move paper to top of next page (form). + No movement. Overtype the previous line. Data Structure The FTP client specifies the structure of files being transferred to and from Sterling Connect:Enterprise. Data structure is significant when transferring files between systems that have different methods of storing files. Some systems store files as file-oriented, whereas others store them as record-oriented. The FTP standard includes three data structures: file, record, and page. Sterling Connect:Enterprise FTP provides the ability to specify two FTP data structures: file and record. Sterling Connect:Enterprise FTP does not support the page structure. File File has no internal structure and is considered a continuous sequence of bytes. File structure can be used with all transfer modes and data types. End-of-file ( ) is indicated when the sender closes the data connection. File is the default data structure for Sterling Connect:Enterprise. 10 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Data Representation and Storage Record The data is sent as a set of sequential records. The record structure is only valid with transfers of text files (data type ASCII or data type EBCDIC). End-of-record ( ) indicators for all records, including the final record, must be explicit. Page The page structure is not implemented in the Sterling Connect:Enterprise FTP feature. Transfer Mode Transfer mode indicates which transmission services Sterling Connect:Enterprise must provide for z/OS FTP server. There are three transfer modes defined in the FTP standard and implemented in Sterling Connect:Enterprise: stream, block, and compressed. Stream Data is transferred as a stream of bytes. Use any of the data types or data structures implemented in the Sterling Connect:Enterprise FTP feature. Stream mode is the default transfer mode for the Sterling Connect:Enterprise server. For the file structure, end-of-file is indicated when the sending host closes the data connection. All bytes transferred are data bytes. For the record structure, the end-of-record ( ) and end-of-file ( ) is identified by 2-byte control sequences. The control sequence must be explicit, including the last record. The and control sequences are not stored as a part of the batch's data. The first byte of a control sequence is the escape code—hexadecimal 'FF'. An sequence is hexadecimal 'FF01'. An sequence is hexadecimal 'FF02'. and can be indicated together on the last byte of the data as hexadecimal 'FF03'. An implicit is indicated when the sender closes the data connection without receiving the sequence. If a data byte contains hexadecimal 'FF', two bytes of hexadecimal 'FFFF' are transmitted and received to prevent the loss of data. The single byte of hexadecimal 'FF' is stored with the batch, not the two bytes of hexadecimal 'FFFF'. Block Data is transferred as a series of blocks. Any of the data types are valid for a block mode transfer. Any of the file structures are valid for block mode transfer. A header precedes each data block. The header is three (3) bytes long and contains a descriptor code and byte count field. The descriptor code is a binary code and is not data type sensitive. The byte count field is an unsigned half-word integer, and is not data type sensitive. The descriptor code is the high-order byte (8 bits) of the header, and defines the block's attributes. The following table contains the valid descriptor codes: IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 11 Chapter 1 Sterling Connect:Enterprise FTP Implementation Dec Code Value Meaning 128 X'80 'End of byte count is EOR 64 X'40 'End of byte count is EOF 32 X'20 'Suspected errors in data block (informational only) 16 X'10 'Data block is a restart marker 0 X'00 'Data continues to next block The count field is the low order two bytes (16 bits) of the header, and contains of the number of bytes in the block excluding the header. Compressed Data is transferred as a series of blocks in a compressed format. ASCII and EBCDIC are the only valid data types for a compressed mode transfer. The only valid data structure for a compressed mode transfer is file. Compressed format transfers contain three kinds of information: uncompressed data, compressed data, and control information. Uncompressed data is transferred as a byte string, and is proceeded by a 1-byte count field. The maximum length of an uncompressed string is 127 bytes. If the byte contains a value from 1 through 127 (hexadecimal '01' through '7F'), it is a count field that describes the number of uncompressed bytes that follow. There are two types of compressed data: replication and filler. ✦ Replication compressed data is represented by a 1-byte count field in front of the replicated character. The count field is the number of times the single character occurs in the data. If the byte contains a value from 128 to 191 (hexadecimal '80' through 'BF'), it is a count of the number of times the next byte is replicated. The first two bits of the byte are ignored. The last six bits contain the number of times the character is replicated. The maximum length of a compressed replicated field is 63 bytes. The replicated character is included in the count field. ✦ Filler compressed data is represented by a 1-byte count field. The count field is the number of filler characters that occur in the data. The filler byte is a blank character. If the byte contains a value from 192 to 255 (hexadecimal 'C0' through 'FF'), it is a count of the number of filler bytes to expand into the data. The first two bits of the byte are ignored. The last six bits contain the number of filler bytes. For ASCII and EBCDIC, the filler byte is a blank character. A blank is ASCII code 32 (hexadecimal '20') or EBCDIC code 64 (hexadecimal '40'). The maximum length of a compressed filler field is 63 bytes. Control information is sent as a 2-byte control sequence. The first byte is an escape ( ) character. The second byte contains a descriptor code. Control information is optional. The count and control sequence fields are not part of the data. The count and control field lengths are not included in the length of the information fields. Data that is read from the TCP/IP stack is decompressed before any translation is done. Each byte read from the TCP/IP stack is examined for the count or control sequence field. 12 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Controlling FTP Connections If the value of the byte is zero (hexadecimal '00'), it is the first byte of a 2-byte control sequence. The first byte of zero is the escape character. The second byte contains a descriptor code. The descriptor codes have the same meaning as in block mode and apply to the succeeding string of bytes. The succeeding string can be an uncompressed data string, a compressed replicated character, or a compressed filler character. The compression count information fields are eliminated when the file is decompressed. The compression control sequence field (hexadecimal 0080') is replaced with the control sequence field, hexadecimal 'FF01'. The compression control sequence field (hexadecimal '0040') is replaced with the control sequence field, hexadecimal 'FF02'. The following table shows which transfer modes you can specify for a given data type and data structure when using the Sterling Connect:Enterprise FTP server. Transfer mode stream, data type ASCII, and data structure file are the defaults for Sterling Connect:Enterprise FTP server. Transfer Mode Data Type Data Structure ASCII EBCDIC Image File Record Stream X X X X X Block X† X X† X X† Compressed X† X X† X X† Note: The combinations marked by a dagger are not currently supported by the IBM z/OS FTP server. When selecting among the options listed, consider the purpose of the file transfer. If programs on the receiving host use the transferred file, select options that make the file usable on the receiving host. If the receiving host is being used as an intermediate storage location for the transferred file, and the file will be retrieved again by the original host, you can select data type image, data structure file, and transfer mode stream. Controlling FTP Connections This section describes considerations for navigating firewalls and using the Clear Control Channel feature. Implementing Firewall Navigation Certain parameters defined in the Option Definition File (ODF) in Sterling Connect:Enterprise enable you to apply restrictions to FTP operations in active and passive FTP mode, enabling you to control FTP connections through your firewall. These parameters enable you to define port ranges, the number of retries if socket acquisition fails, and how long to wait between retries. Although you can specify all available ports on a system in each range, you can control firewall navigation more effectively by assigning a limited number of ports for FTP operations. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 13 Chapter 1 Sterling Connect:Enterprise FTP Implementation Implementing the Clear Control Channel (CCC) Feature Using the CCC feature provides a way to negotiate the control connection from an encrypted content to a clear text content. After the user ID and password have been transmitted in encrypted format, the remainder of the control transmission is in clear text until the connection ends. All data and objects transferred between the client and server remain encrypted. Note: The CCC command is valid for Secure FTP only, and each endpoint of the connection must support the use of this command. Connecting to a Sterling Connect:Enterprise FTP Server The following procedure describes how to connect to a Sterling Connect:Enterprise FTP server. This is a generic procedure and assumes that you have access to an FTP client software package. Your FTP client software can require different procedures. Note: Point and Click FTP systems do not have a command line. The prerequisite information is included during installation. Prerequisites Obtain the following information from your Sterling Connect:Enterprise administrator: ✦ Sterling Connect:Enterprise FTP server IP address or host name and port number or range of ports ✦ User name or remote name and password ✦ Mailbox ID Log On 1. At the command line prompt, issue the following command: > ftp host_name port_number If your FTP client does not allow parameters on the initial ftp command, use the following two commands to establish the connection: > ftp > open host_name port_number [port_range(s)] where “host_name” and “port_number” are the server IP address or host name and port number obtained from the Sterling Connect:Enterprise administrator, and “port_range(s)” limits the port or range of ports available for FTP transmissions through firewalls. 14 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Sterling Connect:Enterprise FTP Server and Equivalent Client Commands The Sterling Connect:Enterprise FTP server sends the following messages when the connection is complete, where: 220-Connect:Enterprise vv.rr.mm on opsys_name opsys_rel. 220-Connection will close if idle for more than discintv. 220 Ready (at local host date and time) yyyy/mm/dd at hh:mm:ss vv.rr.mm is the version, release, and modification level of Sterling Connect:Enterprise at the host site. opsys_name is the standard name for the operating system executing Sterling Connect:Enterprise. opsys_rel is the release information of the operating system. discintv is the idle disconnect interval. The idle disconnect interval is the number of seconds that the FTP client and FTP server connection remains open with no activity. The Sterling Connect:Enterprise FTP server forces the session to end by closing the control connection. Get the required disconnect interval from the Sterling Connect:Enterprise administrator at the host site hh:mm:ss and yyyy/mm/dd are the time and date of the connection. The time and date of the connection is the Sterling Connect:Enterprise local time and date. Batches added by the FTP client are posted using the Sterling Connect:Enterprise local time and date. 2. The FTP client prompts you for your user name. The user name is assigned by the Sterling Connect:Enterprise administrator and is referred to as the remote name. If the FTP client does not prompt you for your user name, type the following command: > user username 3. The FTP client prompts you for your password. The initial password is assigned by the Sterling Connect:Enterprise administrator. When you are connected, the current working mailbox ID is the same as your user name. Sterling Connect:Enterprise FTP Server and Equivalent Client Commands This section describes the standard FTP commands that the Sterling Connect:Enterprise FTP server accepts along with the typical FTP client commands that invoke them. They are labeled typical FTP commands because some FTP client interface panels contain non-standard commands, like get, instead of the standard FTP commands, like retr. The client software translates a non-standard FTP client command into a standard FTP command before sending it to the FTP server. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 15 Chapter 1 Sterling Connect:Enterprise FTP Implementation The following table describes terminology specific to Sterling Connect:Enterprise FTP. The Sterling Connect:Enterprise terms have synonyms that may be more familiar to experienced FTP users. Sterling Connect:Enterprise Term Synonym Mailbox ID Directory Batch ID or user batch ID File name Batch Number Batch Number Note: In Sterling Connect:Enterprise, it is possible for a mailbox ID to contain identical batch IDs or file names. The unique identifier for individual files in Sterling Connect:Enterprise thus becomes the batch number. The exact format in which you issue a command depends on your operating system and follows any conventions required. For example, the Help command can provide help from your own operating system but not from Sterling Connect:Enterprise. Caution: If you are issuing FTP commands from a client that does not use a Point and Click system, inconsistent results may occur if you do not follow the conventions of your operating system. The dialog feature of Sterling Connect:Enterprise provides a way to track and troubleshoot inconsistencies that result from failure to adhere to your operating system conventions for commands. All transmissions between Sterling Connect:Enterprise FTP client and server are monitored and written to a dialog log file at the client site. This file lists each transmission, the command you thought you were issuing, and the command that Sterling Connect:Enterprise actually received. In addition, any error or confirmation messages returned by Sterling Connect:Enterprise are recorded in this file. Coordinate with your host site administrator to turn dialog on as the default for your site. If you do not want dialog on as a default, you can issue the $$DIALOG command from the command line to turn it on temporarily and troubleshoot for a particular session. Sterling Connect:Enterprise FTP supports only the FTP commands in the following table, which lists FTP client commands available for a remote FTP client and the equivalent FTP command invoked by the Sterling Connect:Enterprise FTP server. When necessary, the Sterling Connect:Enterprise FTP description states how the Sterling Connect:Enterprise FTP implementation differs from the standard. Variations from the standard FTP commands are detailed in Sterling Connect:Enterprise Variations from Standard FTP Commands on page 35. 16 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Sterling Connect:Enterprise FTP Server and Equivalent Client Commands Command Invoked by Sterling Connect:Enterprise FTP Server FTP Client Command Standard Description Sterling Connect:Enterprise FTP Implementation ABOR abort Terminates the current data transfer. If a data transfer is not occurring, ABOR does not affect the session. Same as standard Invalid if issued prior to logon completion. AUTH AUTH Identifies the security mechanism used. Required to initiate a secure FTP session. SSL and TLS are the only security mechanism supported. Same as standard Must be received prior to the USER and PASS commands. CCC CCC Secure FTP only. Negotiates the control connection from an encrypted content to a clear-text content after the user ID and password have been transmitted in encrypted format. All data and objects transferred between client and server remain encrypted. Both ends of the connection must support this command. Negotiate a clear-text control channel. CWD cd Change working directory See table Note. Invalid if issued prior to logon completion. Change current working mailbox ID delete and mdelete Delete a file DELE See table Note. HELP HELP Invalid if issued prior to logon completion. Logically delete batches from the current working mailbox ID This command does NOT delete the batch permanently. The information is recoverable until a purge is performed. Display help information Same as standard Invalid if issued prior to logon completion. LIST dir List file information Invalid if issued prior to logon completion. List batches in the current working mailbox ID Note: By default, anonymous remote sites can execute all commands except CWD and DELE. The security exit or security interface can further limit the abilities of anonymous remote sites. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 17 Chapter 1 Sterling Connect:Enterprise FTP Implementation Command Invoked by Sterling Connect:Enterprise FTP Server FTP Client Command Standard Description Sterling Connect:Enterprise FTP Implementation NLST ls, mdelete, mget Names only list List user batch IDs in the current working mailbox ID MODE mode Transfer mode Same as standard NOOP NOOP No operation Same as standard Invalid if issued prior to logon completion. Invalid if issued prior to logon completion. PASV PASV Listen on alternate port Same as standard Invalid if issued prior to logon completion. PASS PASS Password Same as standard PBSZ PBSZ Specifies maximum buffer size in bytes of encrypted data sent or received during file transfer. Must occur prior to PROT command. Same as standard Valid if issued prior to logon completion. PORT port Host data port number Same as standard PROT PROT Indicates the type of data channel protection used by client and server during transfer. Same as standard P is the only value currently supported. Indicates all data on channel is encrypted. PWD pwd Print current directory name Print current working mailbox ID QUIT QUIT Disconnect Same as standard RETR RETR, get, mget Transfer (get) a file Retrieve batches from the current working mailbox ID SITE Site-specific information SITE Invalid if issued prior to logon completion. Same as standard Invalid if issued prior to logon completion. STAT STAT Send status Same as standard Invalid if issued prior to logon completion. Note: By default, anonymous remote sites can execute all commands except CWD and DELE. The security exit or security interface can further limit the abilities of anonymous remote sites. 18 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide SITE Command Parameters Command Invoked by Sterling Connect:Enterprise FTP Server FTP Client Command Standard Description Sterling Connect:Enterprise FTP Implementation STOR STOR, put, mput Transfer a file Add a batch to the current working mailbox ID STOU Store a file with a unique name STOU Invalid if issued prior to logon completion. Invalid if issued prior to logon completion. Add a batch to the current working mailbox ID STRU STRU Set file transfer structure Same as standard SYST SYST Type of operating system Same as standard TYPE TYPE Data representation type Same as standard Valid if issued prior to logon completion. USER USER User name Same as standard Note: By default, anonymous remote sites can execute all commands except CWD and DELE. The security exit or security interface can further limit the abilities of anonymous remote sites. Sterling Connect:Enterprise commands are not case-sensitive. Sterling Connect:Enterprise FTP server translates all commands to upper case. For example, "Help" is the same as "help," "HELP," and "helP" All commands end with a carriage-return-line-feed ( is hexadecimal '0D0A') for ASCII and new line ( is hexadecimal '15') for EBCDIC. The symbol denotes a single space (blank). A blank is ASCII code 32 (hexadecimal '30') and EBCDIC code 64 (hexadecimal '40'). SITE Command Parameters The SITE command sets parameters specific to Sterling Connect:Enterprise that affect adding batches (STOR), retrieving batches (RETR), listing batches (LIST), and listing user batch IDs (NLST). You can view the current values of the SITE command parameters using the STAT command. Refer to Sample Output of STATUS Command on page 28. Multiple parameters can be specified on the SITE command. Specifying the SITE command with the RESET parameter sets all of the SITE parameter's values to the session default value. IDENT parameters are not affected by RESET. The values set for a SITE command parameter remain in effect for the remainder of the session, except for the DIR_FILTER and LS_FILTER parameters. The DIR_FILTER and LS_FILTER parameter value changes are only effective for the next execution of the LIST or NLST command, IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 19 Chapter 1 Sterling Connect:Enterprise FTP Implementation respectively. To make the DIR_FILTER and LS_FILTER parameter values effective for the remainder of the session, specify the KEEP option. No security checks are made for the SITE command. The following table lists the parameters valid for the SITE command. The column labeled “FTP server Command” lists the Sterling Connect:Enterprise FTP server command that is affected by the parameter listed. The column labeled “Remote FTP Client Command” lists the typical FTP client command that invokes the FTP server command affected by the parameter. 20 SITE Parameter Description FTP Server Command Remote FTP Client Command BCHSEP=NONE|OPT3|OPT4 Batch separation options. See Note 1. Note: BCHSEP=OPT4 affects the format of the responses from an NLST command, which can affect the typical FTP client mdelete and mget commands. See Batch Status Flags on page 41 for an explanation of the BCHSEP options. NLIST, RETR get, ls, mdelete, mget BLKSIZE=0-32760 or blank Block size of allocated file being sent. STOR, STOU put, mput BLOCKS Primary allocation amount of file being sent is in BLOCKS. STOR, STOU put, mput BLOCKSIZE=0-32760 or blank Block size of file being sent. STOR, STOU put, mput COLL_EMPTY_BATCH= NO|YES Specifies whether to collect a batch containing no user data and treat it as a valid empty batch. If NO is specified, the incomplete flag is set for empty batches. If YES is specified, the incomplete flag is not set for empty batches. STOR, STOU put, mput 1 The default values for these parameters are specified in the *REMOTES sections of the ODF by the Sterling Connect:Enterprise administrator. 2 FTIME, ORIGIN, and TTIME affect the contents of the response from an NLST command. The response from the NLST command affects the typical client mdelete and mget commands. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide SITE Command Parameters SITE Parameter Description FTP Server Command Remote FTP Client Command CYLINDERS Primary allocation amount of file being sent is in CYLINDERS. STOR, STOU put, mput DIR_FILTER [QUERY] Display batch exclusion filter. N/A N/A DIR_FILTER DEFAULT|NONE|OFF [KEEP] Reset batch exclusion filter. LIST dir DIR_FILTER= [KEEP] Specify batch exclusion filter. LIST dir DIRECTORY=1-16777215 or blank Number of directory blocks allocated for file being sent. STOR, STOU put, mput DIRFORM=BROWSER| BROWSER64|MBOX_CLIENT| MBOX_CLIENT64| MBOX_EXT1_CLIENT64| MBOX_ZOS|MBOX_ZOS64| $MBINSDFXYKORV|UNIX|UNIX64 Reply format options. The values following the $ can be specified in any order to achieve the desired directory display format. Any number of options can be specified. See Different DIRFORM Layouts Returned by LIST on page 31 for examples. LIST dir See Note 1. See Note 1. . $ User-defined format M 8-character mailbox ID B 24-character user batch ID. I 24-character batch ID. N 7-digit batch number (#nnnnnn) S 8-11 digit file size in number of bytes, based on high order significant digit (CT=nnnnnnnn[nnn]) D time/date of batch creation (hhmm-yyddd) F Batch status flags. X 64-character Batch ID (BID=xxxx….xxxx) Y 64-character Batch ID (xxxx….xxxx) K 15-digit file size in number of bytes (CT=nnnnnnnnnnnnnnn) 1 The default values for these parameters are specified in the *REMOTES sections of the ODF by the Sterling Connect:Enterprise administrator. 2 FTIME, ORIGIN, and TTIME affect the contents of the response from an NLST command. The response from the NLST command affects the typical client mdelete and mget commands. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 21 Chapter 1 Sterling Connect:Enterprise FTP Implementation SITE Parameter EDI=NO | YES Description O 8-character batch originator (batch job or remote name) R 11-digit record count (REC=nnnnnnnnnnn) V VBQ ID and allocation status (VBQnn [OFFLINE]) Specifies whether single byte x'15' segment terminators are used. FTP Server Command Remote FTP Client Command RETR mget, get STOR, STOU mput, put EDI=YES indicates that X’15’ segment terminators are being used and allows the translation table to translate the X '15' to a single byte. EDI=NO (the default) indicates that X’15’ segment terminators are not being used so standard EBCDIC to ASCII translation is used to translate the X '15' to the 2-byte X '0D0A'. EO=NO|YES Extract once. See Note 1. EO=YES specifies that the batch is extracted and stored one time from a remote client and cannot be transmitted. The default value EO=NO does not prevent transmission or multiple extractions. FIXRECFM Sent by IBM–ignore. STOR, STOU put, mput FTIME= Limit batch selection by specifying the starting date for all data selected for processing. This value is used to calculate dates relative to the current date (for example, FROMDATE=3 is resolved to the date three days ago). The default is 1980001. DELE, LIST, NLST, RETR delete, dir, get, ls, mdelete, mget See Note 2. Valid formats: nnn hhmm yyddd ccyyddd nnn:hhmm yyddd:hhmm ccyyddd:hhmm 22 1 The default values for these parameters are specified in the *REMOTES sections of the ODF by the Sterling Connect:Enterprise administrator. 2 FTIME, ORIGIN, and TTIME affect the contents of the response from an NLST command. The response from the NLST command affects the typical client mdelete and mget commands. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide SITE Command Parameters SITE Parameter Description FTP Server Command Remote FTP Client Command IDENT PROD_ID=n PROD_REL=x.x.xx Identification of Sterling Connect:Enterprise product. N/A N/A KALIVEOFF Turns off the KALIVEON parameter. N/A N/A Note: KALIVEOFF is equivalent to setting KALIVEON=0. KALIVEON=nnnnnnn Keeps remote control ports open for the specified number of seconds (0–2147460) for non-Sterling Connect:Enterprise applications that experience timeouts on their control ports even though they have data port activity. N/A N/A KIRN=YES | NO (KIRN stands for Keep Input Recsep NL) STOR, STOU put, mput Sterling Connect:Enterprise removes the record separator string so that the batch is stored as a file structure instead of being record-oriented or keeps the record separator string, NL (New Line feed), for incoming SFA and SFE batches or allows. If the batch is not recordized, this parameter is ignored. The default comes from the KIRN setting in the *REMOTES record. NO = Sterling Connect:Enterprise removes the record separator string after recordizing the batch. YES = The Record separator strings are kept in the batch. The corresponding FTP_DEFAULT_RIFS parameter must be set to YES. For more information on recordizing, see the chapter on configuring ODF records for FTP connections in the IBM Sterling Connect:Enterprise for z/OS Administration Guide. LRECL=0-32760 or blank or "x” LRECL of file being sent. STOR, STOU put, mput LS_FILTER [QUERY] Display batch exclusion filter. NLST ls, mdelete, mget 1 The default values for these parameters are specified in the *REMOTES sections of the ODF by the Sterling Connect:Enterprise administrator. 2 FTIME, ORIGIN, and TTIME affect the contents of the response from an NLST command. The response from the NLST command affects the typical client mdelete and mget commands. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 23 Chapter 1 Sterling Connect:Enterprise FTP Implementation SITE Parameter Description FTP Server Command Remote FTP Client Command LS_FILTER DEFAULT|OFF|NONE [KEEP] Reset batch exclusion filter. NLST ls, mdelete, mget LS_FILTER= [KEEP] Specify batch exclusion filter. NLST ls,mdelete, mget Multiple transmission flag. STOR, STOU put Specifies whether or not single quotes are to be used to delimit the start/end of the User Batch ID in the name list returned to the client, in response to a NLST command. The command will remain in effect for the duration of the session or until the command is issued again during that session. NLST ls, mdelete, mget See Note 1. MULTXMIT=NO|YES See Note 1. NLIST_QUOTES=NO|YES NLIST_QUOTES=NO tells the system to not enclose the User Batch ID in single quotes. The default value NLIST_QUOTES=YES encloses the User Batch ID in single quotes. nnnnnn Sent by IBM–ignore. STOR, STOR put, mput ONEBATCH=NO|YES Duplicate user batch ID RETR get, mget Limit batch selection. DELE, LIST, NLST, RETR Delete, dir, get, ls, mdelete, mget PRIMARY=1-16777215 or blank Primary allocation amount of file being sent. STOR, STOU put, mput RECFM= RECFM value for file being sent. STOR, STOU put, mput REMOTE_FILENAME_LENGTH= SHORT|LONG|LONG64 Length of remote file name. NLST ls, mdelete, mget Set all values to default. DELE, LIST, NLST, RETR, STOR, STOU delete, dir, get, ls, mdelete, mget See Note 1. ORIGIN= See Note 2. See Note 1. RESET 24 1 The default values for these parameters are specified in the *REMOTES sections of the ODF by the Sterling Connect:Enterprise administrator. 2 FTIME, ORIGIN, and TTIME affect the contents of the response from an NLST command. The response from the NLST command affects the typical client mdelete and mget commands. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide SITE Command Parameters SITE Parameter Description FTP Server Command Remote FTP Client Command RIFS=YES | NO (RIFS stands for Recordize Input File Structure) STOR, STOU put, mput Changes the batch to record structure or retains the batch as file structure. YES = Recordizes the batch after recognizing a record separator string and uses CRLF for SFA batches and NL for SFE batches. NO = Retains file structure of batch and does not recognize record separator strings in SFA or SFE batches. The default comes from the RIFS setting in the *REMOTES record. For more information on recordizing, see the chapter on configuring ODF records for FTP connections in the IBM Sterling Connect:Enterprise for z/OS Administration Guide. Note: Processing results cannot be predicted or supported when RIFS=NO and SCAN is set to YES or ALL. 1 The default values for these parameters are specified in the *REMOTES sections of the ODF by the Sterling Connect:Enterprise administrator. 2 FTIME, ORIGIN, and TTIME affect the contents of the response from an NLST command. The response from the NLST command affects the typical client mdelete and mget commands. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 25 Chapter 1 Sterling Connect:Enterprise FTP Implementation SITE Parameter Description FTP Server Command Remote FTP Client Command SCAN=NO|YES|ALL Specifies whether the Sterling Connect:Enterprise FTP server scans STOR or STOU received batches for $$ commands and /* cards. For more information, see Preparing Batches for the Sterling Connect:Enterprise FTP Server on page 47. STOR, STOU put, mput NO= Scanning for Sterling Connect:Enterprise $$ commands is not enabled. Sterling Connect:Enterprise $$ commands, /*SIGNON, and /*BINASC cards embedded in a received batch are treated as data. YES= Scanning for Sterling Connect:Enterprise $$ commands is enabled initially, but scanning for a subsequent $$ADD card is not automatic. Each $$ADD card must include the parameter SCAN=YES to continue scanning for $$ commands. Use this value to make FTP command scanning behave like it does in SNA. ALL= Scanning for Sterling Connect:Enterprise $$ commands is enabled for the entire batch unless the batch contains a $$ADD card with the parameter SCAN=NO. Use this value to make FTP command scanning behave like it does in BSC. 26 SECONDARY=1-16777215 or blank Secondary allocation amount of file being sent. STOR, STOU put, mput TO=NO|YES Transmit once. TO=YES specifies that the batch being received can only be transmitted once and is not extractable. TO=YES can be thought of as “transmit once, transmit only“. TO=NO specifies that the batch is not marked non-transmittable. STOR, STOU put See Note 1. TRACKS Primary allocation amount of file being sent is in TRACKS. STOR, STOU put, mput 1 The default values for these parameters are specified in the *REMOTES sections of the ODF by the Sterling Connect:Enterprise administrator. 2 FTIME, ORIGIN, and TTIME affect the contents of the response from an NLST command. The response from the NLST command affects the typical client mdelete and mget commands. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide SITE Command Parameters SITE Parameter Description FTP Server Command Remote FTP Client Command TTIME= Limit batch selection by specifying the ending date for all data selected for processing. This value calculates dates relative to the current date. The default is 1980001. DELE, LIST, NLST, RETR delete, dir, get, ls, mdelete, mget See Note 2. Valid formats: nnn hhmm yyddd ccyyddd nnn:hhmm yyddd:hhmm ccyyddd:hhmm VARRECFM Sent by IBM–ignore STOR, STOU put, mput VBQ#=nn Specifies the number of the VBQ file on which batches collected in FTP sessions are to be stored. STOR, STOU dir, get, list, nlist, mget, scget Transmission control STOR, STOU put Specifies whether to transmit an empty batch. If NO is specified, empty batches are not transmitted. If YES is specified, empty batches are transmitted. RETR get, mget Note: You cannot display or update this parameter in the ISPF and CICS screens related to the Options Definition File. Only a SITE or LOCSITE command can direct FTP batches to a VBQ other than the Current Collection VBQ. XMIT=NO|YES To set this value for multiple collections, the command is: LOCSITE VBQ#=nn KEEP KEEP must be the next parameter after VBQ#=nn to retain the value for more than one batch collection unless it part of an MGET command. If nn is 00, the assignment resets to the Current Collect VBQ. If nn is 01 through 20 that particular VBQ is allocated. See Note 1. XMIT_EMPTY_BATCH= NO|YES 1 The default values for these parameters are specified in the *REMOTES sections of the ODF by the Sterling Connect:Enterprise administrator. 2 FTIME, ORIGIN, and TTIME affect the contents of the response from an NLST command. The response from the NLST command affects the typical client mdelete and mget commands. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 27 Chapter 1 Sterling Connect:Enterprise FTP Implementation Sample Output of STATUS Command The type of information returned depends on the remote server. If the remote FTP server is a Sterling Connect:Enterprise system, the status and setting information is displayed in the following messages: 211-Connect:Enterprise at 10:09:49 on 2003.275 host time. 211-Session started at 10:09:33 on 2003/275 host time. 211-User: FTPRMT Current working Mailbox ID: FTPRMT 211-TYPE: A MODE: S STRUcture: F 211-Local SITE option values: 211- Allocation type=NONE BCHSEP=NONE BLKSIZE=0 211- DIR_FILTER=18Fe DIRECTORY=0 211- EO=NO 211211211211211 211 FTIME=1980001:0000 LRECL=0 DIRFORM=MBOX_ZOS LS_FILTER=BDI!RST MULTXMIT=NO ONEBATCH=NO ORIGIN= PRIMARY=0 RECFM= REMOTE_FILENAME_LENGTH=LONG SECONDARY=0 TO=NO TTIME= XMIT=NO VBQ=01 SCAN=NO 0 Kbytes received for 0 batches during this session 0 Kbytes sent from 0 batches during this session COLL_EMPTY_BATCH=NO XMIT_EMPTY_BATCH=NO In addition to the following SITE parameter setting information, the time the session started is shown (in hh:mm:ss and yyyy.ddd format) along with the number of bytes and batches received and sent during the session. The following table lists the information for each data label in alphabetical order: 28 Data Label Description Allocation type The type of allocation used – BLOCKS, CYLINDER, TRACKS or NONE. AUTH The security mechanism used (SSL or TLS). BCHSEP The batch separation option used – NONE, OPT3, or OPT4 option. See BCHSEP=NONE|OPT3|OPT4 on page 20. BLKSIZE The file block size. Current working Mailbox ID The name of the current working mailbox. DIR_FILTER The filter used by the LIST command to exclude batches from the list returned to the remote FTP client. Refer to DIR_FILTER= [KEEP] on page 21. DIRECTORY The file directory size. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide SITE Command Parameters Data Label Description DIRFORM The DIRFORM reply format. Refer to DIRFORM=BROWSER| BROWSER64|MBOX_CLIENT| MBOX_CLIENT64| MBOX_EXT1_CLIENT64| MBOX_ZOS|MBOX_ZOS64| $MBINSDFXYKORV |UNIX |UNIX64 on page 21. EO Indicates if the file can be extracted once (EO) and transmitted (Yes or No). FTIME The date in year, month, day format followed by a semicolon and time in hours and minutes representing the from time parameter. Specifies the starting date for all data selected for processing. The nnn (1–3 digit number) value calculates dates relative to the current date. If nnn is specified, the FROMDATE value is calculated as today-nnn (for example, FROMDATE=3 is resolved to the date three days ago). The default is 1980001. LRECL The file logical record length. LS_FILTER A filter used by the NLST command to exclude batches from the list returned to the remote FTP client. MODE The mode – blocked (B), compressed (C), or stream (S). MULTXMIT Indicates if the batch being received can be transmitted multiple times (Yes or No). ONEBATCH Indicates if only the first eligible batch can be selected for transfer to the remote FTP client (Yes or No). ORIGIN The name of the remote or user ID of the batch job that added the batch. PBSZ The size of the protection buffer. PRIMARY The file primary allocation amount. PROT The type of data channel protection used by client and server during transfer. (P indicates all data on the channel is encrypted.) RECFM The file record format. REMOTE_FILENAME_LENGTH The length of the Batch ID returned by NLST (short or long). SCAN The last known value of the remote (server-side) SCAN setting, which indicates whether the Sterling Connect:Enterprise FTP server is scanning RETR received batches for $$ commands and /* cards. For more information, see the description for the SCAN parameter on page 26. SECONDARY The file secondary allocation amount. STRUcture The file structure – file (F) or record (R). TO Indicates if the file can only be transmitted once (TO) and cannot be extracted (Yes or No). IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 29 Chapter 1 Sterling Connect:Enterprise FTP Implementation Data Label Description TTIME The date in year, month, day followed by a semicolon and time in hours and minutes representing the to time (TTIME) parameter. TYPE The file type – ASCII (A), EBCDIC (B), or BINARY (I). User The name of the user ID currently logged into the remote FTP Server. XMIT Indicates if the batch is available to be transmitted to other sites (Yes or No). VBQ The number of the VBQ file on which batches collected in FTP sessions are to be stored. VSAM Batch Status Flags The DIR_FILTER parameter uses the values in the following batch status flags. Some combinations of these flags are always processed together or are not accepted. For example: ✦ A batch with flag 8 or 9 also has an F flag. (DIR_FILTER=89 is stored in the Remote definition as DIR_FILTER=F) (DIR_FILTER=!8!9 is stored in the Remote definition as DIR_FILTER=!F) ✦ A batch with any combination of 1, 2, or 3 is not accepted. 30 Code Description A The batch was added by the offline ADD utility. B The batch originated at a BSC remote site. C The batch was collected from a remote site through online Sterling Connect:Enterprise. D The batch is flagged for deletion due to an online $$DELETE request or an offline DELETE utility. e The batch was encrypted when added by the offline ADD utility. E The batch was extracted by the offline EXTRACT utility. This flag does not inhibit another EXTRACT from running and does not prevent online access to the batch. F The batch originated at an FTP remote site. I The batch is incomplete. Either no records were in the batch, or an online data collection was interrupted due to an error condition. This batch is ignored by Sterling Connect:Enterprise and only the EXTRACT utility can extract it. M The batch is available for multiple transmission, can be transmitted to any remote site, and is not marked T when transmitted unless mailboxID = AC Listname. N Nontransmittable. The batch is locked for transmissions. The status is set immediately after the batch is successfully collected, when the EO=Y option of a $$ADD command is specified. It is also set following successful transmission of a batch added with the TO=Y parameter. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide SITE Command Parameters Code Description R Requestable. A remote site can request the batch or a host-initiated Auto Connect can transmit the batch. S The batch originated at an SNA remote site. T The batch was transmitted online to a remote site. U Unextractable. When displayed, this status replaces the E status. The batch is locked for extractions. This status is set immediately after the batch is added, when the TO=Y option added the batch. It is also set following successful extraction of the batch when the EO=Y option was used to add the batch. X The batch contains transparent data. Z EBCDIC data added through the APPC user API. 0 The batch is sorted on the VBQ as FILE_STRUCTURE (non record oriented). The batch was added offline or collected online as a contiguous byte string with no logical record delineation. 1 FTP mode is blocked. 2 FTP mode is compressed. 3 FTP mode is stream. 4 FTP collected SSL. 8 FTP structure is file. 9 FTP structure is record. Different DIRFORM Layouts Returned by LIST The layout of the information returned by the LIST command depends on the value of the DIRFORM parameter of the SITE command. The format returned when DIRFORM=MBOX_ZOS64 is shown in the following example, which illustrates the default directory list format. (1) (2) (3) (4) COMPANYB #0000047 CT=00000320 BID=LIST TEST COMPANYB #0000067 CT=00000420 BID=LIST COMPANYB #0000068 CT=00000210 BID=LIST Column Description (1) Mailbox where the batch resides. (2) Batch number–zero filled. (3) Size of batch in bytes. (4) Batch ID IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide (5) 1508-01199 1046-01205 1046-01205 (6) A R C T C F F F O38 O38 O38 (7) (8) VBQ01 OFFLINE VBQ20 VBQ03 31 Chapter 1 Sterling Connect:Enterprise FTP Implementation Column Description (5) Date batch added (HHMM-YYDDD) (6) Batch flags in 20 character field in the following order: I = Incomplete A|C = Offline Added, Online Collected D = Delete N = Not Transmittable U = Unextractable R = Requestable T = Transmitted E = Extracted M = Multi-transmittable X = Transparent B|F|S|Z = BSC, FTP, SNA or API Space = Reserved for future use. Space = Reserved for future use. 0 = File oriented data. 1|2|3 =FTP mode – blocked, compressed, stream 8|9 = FTP structure – file, record e = Offline added with encryption (ENCR=) Space = Reserved for future use. Space = Reserved for future use. Space = Reserved for future use. (7) The number of the VSAM Batch Queue where the batch is stored. (8) VBQ status–OFFLINE if VBQ is not available or blank if available. The format returned when DIRFORM=BROWSER is shown below with an explanation of the columns: (1) A R C T IC 32 (2) (3) (4) (5) 1 COMPANYB 0000047 00000320 JUL 1 COMPANYB 0000067 00000420 JUL 1 COMPANYB 0000074 00000320 JUL (6) (7) 18 15:08 LIST TEST 24 10:46 LIST 24 11:31 July Invoice IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide SITE Command Parameters Column Description (1) Batch flags in 10-character field in the following format: I = Incomplete A|C = Offline added, Online Collected D = Delete R = Requestable T = Transmitted E = Extracted M = Multi-transmittable U = Unextractable N = Not transmittable X = Transparent (2) Constant 1. (3) Mailbox where batch resides. (4) Batch number–zero filled. (5) Size of batch in bytes. (6) Date batch added (MMM DD HH-MM) (7) Batch ID The format returned when DIRFORM=MBOX_CLIENT is shown below with an explanation of the columns. (1) (2) (3) (4) COMPANYB #0000047 CT=00000320 BID=LIST TEST COMPANYB #0000067 CT=00000420 BID=LIST COMPANYB #0000068 CT=00000210 BID=LIST Column Description (1) Mailbox where batch resides. (2) Batch number–zero filled. (3) Size of batch in bytes. (4) Batch ID (5) Date batch added (HHMM-YYDDD) (5) 1508-01199 1046-01205 1046-01205 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide (6) A R C T C (7) COMPANYB COMPANYB COMPANYB 33 Chapter 1 Sterling Connect:Enterprise FTP Implementation Column Description (6) Batch flags in 10-character field in the following order: I = Incomplete A|C = Offline Added, Online Collected D = Delete R = Requestable T = Transmitted E = Extracted M = Multi-transmittable U = Unextractable N = Not transmittable X = Transparent (7) Batch job name or remote name that added the batch. The format returned when DIRFORM=UNIX is shown below with an explanation of the columns. (1) (2) (3) (4) (5) (6) (7) -A-R------ 1 CRONLY 2845 05 AUG 11 20:14 'CRONLY TEST '.#0002845 -A-R------ 1 CRONLY 2846 05 AUG 11 20:14 'CRONLY TEST '.#0002846 -A-R------ 1 CRONLY 2847 05 AUG 11 20:14 'CRONLY TEST '.#0002847 Column Description (1) Batch flags in 10-character field in the following order: I = Incomplete A|C = Offline Added, Online Collected D = Delete R = Requestable T = Transmitted E = Extracted M = Multi-transmittable U = Unextractable N = Not transmittable X = Transparent Note: A hyphen (-) is returned as a placeholder for each batch status which is not present. 34 (2) Constant 1. (3) Mailbox ID where batch resides. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Sterling Connect:Enterprise Variations from Standard FTP Commands Column Description (4) Size of batch in bytes (5) Date batch added (YY month DD HH:MM), where month = Jan, Feb, ...., Nov, Dec. (6) Batch ID, enclosed in single quotes with .#nnnnnnn appended, where nnnnnnn = batch number, for example, '24 character batchid '.#0001234 Sterling Connect:Enterprise Variations from Standard FTP Commands The Sterling Connect:Enterprise FTP server uses a construct called a mailbox ID as the equivalent of the directory in other FTP implementations. Sterling Connect:Enterprise supports a single level of the directory, which is referred to as the current working mailbox ID. The following table summarizes the typical FTP commands that are implemented by the Sterling Connect:Enterprise FTP server in a manner that differs from other FTP server implementations. The way that Sterling Connect:Enterprise implements each command is detailed. The syntax and format for specifying user batch ID are also detailed. . FTP Command Sterling Connect:Enterprise FTP Server Command Sterling Connect:Enterprise Implementation del, delete, mdelete DELE Logically delete batches from the current working mailbox ID dir LIST, NLST List batches in the current working mailbox ID get, mget RETR Retrieve batches from the current working mailbox ID ls, mdelete, mget NLST List the user batch IDs in the current working mailbox ID put, mput, STOU STOR, STOU Add a batch to the current working mailbox ID cd CWD Change current working mailbox ID pwd PWD Print current working mailbox ID User Batch ID Syntax and Formats The value of the user batch ID is case-sensitive and you cannot use the following characters in the user batch ID. The results of attempts to retrieve batches using FTP commands that contain wildcards in the user batch ID are unpredictable. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 35 Chapter 1 Sterling Connect:Enterprise FTP Implementation - . * ? [ ] \ / Additionally, do not use the number symbol (#) as the first character in the user batch ID. Caution: Some systems support ID numbers using the # character, but Sterling Connect:Enterprise can return inconsistent, redundant, or incorrect responses to queries that use # as the first character of the user batch ID. Pathnames, or ‘ ’, consist of an optional Mailbox ID and a User Batch ID in the form: ‘[/ /] ’. Specifying the Mailbox ID in the overrides the setting of the current working mailbox for the current command and the current working Mailbox ID is not changed. If is not specified as part of the path name, then the current working Mailbox ID is used. The user batch ID can be specified in one of the following ways: Format Description nnnnnnn The 1–7 digit batch number from 1–9999999. Leading zeros are optional. “generic-name” 1–64 characters used to identify batches in the current working mailbox ID. (The quotation marks are required for this form of batch ID. Do not use wildcard characters in the “generic-Name” value.) ‘specific’ 1–64 character user batch ID left justified, padded with trailing blanks. The single quotes are required to delimit the ID. If the ID contains an apostrophe, two apostrophes must be encoded for each single apostrophe in the ID. Example: UID1235’BNK1 would need to be encoded ‘UID1235”BNK1’ If blanks are embedded within the ID, the single quotes must be left off. Example: UID1235 BNK1 ‘SPEC*?[]’ Indicates any batch that matches the specified pattern. 1–64 characters including any wildcard card characters. The pattern is compared to all batches in the current working mailbox ID and any matching batches are selected. ‘batch_ID.#nnnnn nn’ 1–64 character ID with trailing blanks truncated, followed by .# and the 7-digit batch number from 0000001–9999999 (including leading zeros) and enclosed in single quotes. Without the single quotes, you cannot use embedded blanks in this ID. This format is normally seen as part of a RETR or DELE command. ‘#nnnnnnn.dat’ # and the 7-digit batch number from 0000001–9999999 with leading zeros followed by .dat and optionally enclosed in single quotes. This format is typically used as part of a RETR or DELE command. 36 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Sterling Connect:Enterprise Variations from Standard FTP Commands delete or mdelete Command In Sterling Connect:Enterprise, the DELE command logically deletes batches from the current working mailbox ID specified by the parameter. You can set the current working mailbox ID using the FTP client cd command. Display the current working mailbox ID using either the STAT command or the PWD command. A mailbox ID specified in temporarily overrides the permanent setting of the current working mailbox ID, for the duration of the current command. The FTIME, ORIGIN, and TTIME parameters of the SITE command affect DELE processing. Set the FTIME, ORIGIN, and TTIME parameters using the SITE command and display them using either the STAT command or the PWD command. The following two security checks are made before the DELE command deletes a batch: ✦ Session security exit call ✦ Security interface security checks Note: Remote sites with the name anonymous are not permitted to use DELE. Sterling Connect:Enterprise FTP del, delete, and mdelete Command Syntax The typical FTP client delete and mdelete commands invoke the FTP server DELE command as shown in the following table. Required parameters are displayed in bold font. No optional parameters are available. FTP Command Sterling Connect:Enterprise FTP Server Command Syntax Parameter Description del, delete, mdelete DELE Required. specifies the batch or batches to delete. DELE Batch Selection with Sterling Connect:Enterprise FTP del Command If the user batch ID specified in is in the form '#nnnnnnn', 'nnnnnnn', 'batch_ID.#nnnnnnn', or '#nnnnnnn.dat' and the batch is in the current working mailbox ID, the single batch with batch number 'nnnnnnn' is deleted. Note: Your operating platform may not support using the number (#) character as the first character of a batch_ID. See Transfer Mode on page 11. If the user batch ID specified in is in form “generic-name”, 'specific', or 'spec*?[]', all batches in the current working mailbox ID that match the value specified are eligible for deletion. An eligible batch is selected for deletion if the following conditions are met: IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 37 Chapter 1 Sterling Connect:Enterprise FTP Implementation 1. The batch's creation date and time is on or after the value specified in the FTIME parameter. 2. The batch's creation date and time is on or before the value specified in the TTIME parameter. 3. The batch's origination matches the value of the ORIGIN parameter or the ORIGIN parameter is blank. If the user batch ID specified in is in '#nnnnnnn', 'nnnnnnn', 'batch_ID.#nnnnnnn', or '#nnnnnnn.dat' format, the SITE parameters FTIME, ORIGIN, and TTIME are ignored. The SITE parameters FTIME and TTIME limit the selection of batches based on the batch's earliest and latest creation date and time, respectively. The ORIGIN parameter limits the selection of batches based on the name of the user or remote that created the batch. dir Command In Sterling Connect:Enterprise the LIST command lists batches in the current working data repository or the mailbox ID specified in the parameter. You set the current working mailbox ID using the FTP client cd command. Display the current working mailbox ID using either the STAT command or the PWD command. For the dir command, the mailbox ID specified in overrides the setting of the current working mailbox ID, but does not change its value. Note: The current data representation must be either ASCII or EBCDIC. Image type is unsupported and is not recognized. The DIR_FILTER, FTIME, ORIGIN, and TTIME parameters of the SITE command affect LIST processing. The DIR_FILTER, FTIME, ORIGIN, and TTIME parameters are set using the SITE command and displayed using either the STAT command or the PWD command. The sequence of the list returned by the LIST command is in ascending order by mailbox ID. The batches listed for each mailbox ID are sequenced based on the values of the batch transmission status and batch age. The batches in the data repository that did not transmit are listed first in ascending sequence by creation date and time. The batches that transmitted are listed last in ascending sequence by creation date and time. The format of the list returned by the LIST command depends on the value of the DIRFORM parameter of the FTP server SITE command. The DIRFORM parameter is set using the FTP server SITE command and displayed using the FTP server STAT command. The following two security checks are made before the LIST command accesses the data repository: ✦ Session security exit call ✦ Security interface security checks If you did not specify a data connection port (using either the PORT or PASV command) before issuing the dir command, Sterling Connect:Enterprise assumes that the data uses the client's control connection port and the server's port adjacent to the control port (for example, L–1). Always specify the data connection port explicitly (through PORT or PASV commands) instead of assuming the default. 38 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Sterling Connect:Enterprise Variations from Standard FTP Commands Sterling Connect:Enterprise FTP dir Command Syntax The typical FTP client dir command invokes the FTP server LIST command as shown in the following table. Required parameters are displayed in bold font. FTP Command Sterling Connect:Enterprise FTP Server Command Syntax Parameter Description dir, LIST, NLST LIST LIST[ ] Optional. specifies the batch or batches to list Batch Selection with Sterling Connect:Enterprise FTP dir Command If the user batch ID specified in is formatted as '#nnnnnnn', 'nnnnnnn', 'batch_ID.#nnnnnnn', or '#nnnnnnn.dat' and the batch is in the current working mailbox ID, the single batch with batch number 'nnnnnnn' is eligible for the list. If the user batch ID specified in is in the form “generic-name”, 'specific', or 'spec*?[]', all of the batches in the current working data repository that match the specified value are eligible for the list. If is not specified, all of the batches in the current working data repository are eligible for the list. Eligible batches are selected for listing depending on the current settings of the SITE parameters DIR_FILTER, FTIME, ORIGIN, and TTIME. An eligible batch is listed if the following conditions are met: ✦ The batch's status flags do not match any of the values specified in the DIR_FILTER parameter. ✦ The batch's creation date and time is on or after the value specified in the FTIME parameter. ✦ The batch's creation date and time is on or before the value specified in the TTIME parameter. ✦ The batch's origination matches the value of the ORIGIN parameter or the ORIGIN parameter is blank. If the user batch ID specified in is in '#nnnnnnn', 'nnnnnnn', 'batch_ID.#nnnnnnn', or '#nnnnnnn.dat format', the DIR_FILTER, FTIME, ORIGIN, and TTIME parameters are ignored. ✦ The DIR_FILTER parameter limits the selection of batches based on a batch's status flags. ✦ The FTIME and TTIME parameters limit the selection of batches based on the batch's earliest and latest creation date and time, respectively. ✦ The ORIGIN parameter limits the selection of batches based on the name of the user or remote that created the batch. get or mget Command In Sterling Connect:Enterprise, the RETR command retrieves batches from the current working data repository or the mailbox ID specified in the parameter. For this command, the mailbox ID specified in overrides the setting of the current working mailbox ID, but IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 39 Chapter 1 Sterling Connect:Enterprise FTP Implementation does not change its value. Set the current working mailbox ID using the FTP client cd command. Display the current working date repository using either the STAT command or the PWD command. The FTP client creates the file names at the remote site using the typical FTP client get and mget commands, and using the replies returned from the NLST command. Several parameters of the SITE command affect RETR processing. You can set these parameters using the SITE command and display them using either the STAT command or the PWD command. Several other parameters of the SITE command cause file characteristics to be stored with the batch. Note: BCHSEP does not affect the selection of batches. It only determines when a batch is marked transmitted. The following two security checks are made before the RETR command retrieves a batch: ✦ Session security exit call ✦ Security interface security checks Before issuing this command, specify the data collection port using either the PORT command or the PASV command. Sterling Connect:Enterprise assumes that the data connection uses the client's control connection port and the server's port adjacent to the control port (for example, L–1). For optimum performance, always specify the data connection port explicitly (through the PORT or PASV commands) instead of assuming the default. When the control connection is established and secure, SSL negotiation of the data connection is expected. Sterling Connect:Enterprise FTP get Syntax The typical FTP client get and mget commands invoke the FTP server RETR command as shown in the following table. Required parameters are displayed in bold font. No optional parameters are available. FTP Command Sterling Connect:Enterprise FTP Server Command Syntax get, mget RETR Required. specifies the batch or batches to be listed. RETR Parameter Description Batch Selection If the user batch ID specified in is in the form '#nnnnnnn', 'nnnnnnn', 'batch_ID.#nnnnnnn', or '#nnnnnnn.dat' and the batch is in the current working data repository, the single batch with batch number 'nnnnnnn' is eligible for retrieval. 40 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Sterling Connect:Enterprise Variations from Standard FTP Commands If the user batch ID specified in is in the form “generic-name”, 'specific', or 'spec*?[]', all of the batches in the current working data repository that match the user batch ID are eligible for retrieval. Eligible batches are selected for listing depending on the current settings of the SITE parameters TIME, ORIGIN, and TTIME, and of the data representation type. A batch is selected for retrieval when the following conditions are met: ✦ The batch is contained in an online VBQ. ✦ The data representation type of the batch matches that of the TYPE parameter. ✦ The batch's creation date and time is on or after the value specified in the FTIME parameter. ✦ The batch's creation date and time is on or before the value specified in the TTIME parameter. ✦ The batch's origination matches the value of the ORIGIN parameter or the ORIGIN parameter is blank. ✦ The batch is requestable. If the user batch ID specified in is in '#nnnnnnn', 'nnnnnnn', 'batch_ID.#nnnnnnn', or '#nnnnnnn.dat' format, the SITE parameters FTIME, ORIGIN, and TTIME are ignored. ✦ The FTIME and TTIME parameters limit the selection of batches based on the batch's earliest and latest creation date and time, respectively. ✦ The data representation type of the batch limits the selection of batches based on current setting of the TYPE parameter. ✦ The ORIGIN parameter limits the selection of batches based on the name of the user or remote that created the batch. Batch Transmission If batches are selected for retrieval, the batches are transferred through the data connection. If the user batch ID specified in is in the form '#nnnnnnn', 'nnnnnnn', 'batch_ID.#nnnnnnn', or '#nnnnnnn.dat' and the batch is in the current working data repository, the single batch with batch number 'nnnnnnn' is eligible for retrieval unless the data representation type does not match. If ONEBATCH=NO is specified, the RETR command concatenates all the batches selected and sends them as one file. If ONEBATCH=YES is specified, the RETR command only sends the first batch selected. Batch Status Flags The batch status flags have the following meaning. ✦ If BCHSEP=NONE or BCHSEP=OPT4, each batch is flagged as transmitted (“T”) when it is sent successfully. If a failure occurs during transmission, BCHSEP=NONE or BCHSEP=OPT4 prevents batches previously sent from being retransmitted. If the transmission is restarted to the same remote client file, the data from the previous batches is replaced with the data from the unsent batches, and the data from the previously sent batches are lost. If the transmission is restarted to a different remote client file, data sent in previous batches are not lost. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 41 Chapter 1 Sterling Connect:Enterprise FTP Implementation ✦ If BCHSEP=OPT3, all batches are flagged as transmitted (“T”) when all of the batches are sent successfully. If a failure occurs during transmission, BCHSEP=OPT3 permits all batches to be transmitted again. If the transmission is restarted to the same remote client file, the data from the previous batches are retransmitted with no loss of data. If the transmission is restarted to a different remote client file, duplicate records are sent to the remote site. put or mput Command (STOR) In Sterling Connect:Enterprise, the STOR command adds a batch to the current working data repository or the mailbox ID specified in the parameter. Set the current working mailbox ID using the FTP client cd command. Display the current working data repository using either the STAT command or the PWD command. For this command, the mailbox ID specified in overrides the setting of the current working mailbox ID, but does not change its value. Several parameters of the SITE command affect STOR processing. You can set these parameters using the SITE command and display them using either the STAT command or the PWD command. Several other parameters of the SITE command cause file characteristics to be stored with the batch. The following two security checks are made before the STOR command adds a batch: ✦ Session security exit call ✦ Security interface security checks A unique batch number is assigned to every batch that is added allowing Sterling Connect:Enterprise to support duplicate user batch IDs. Before issuing this command, specify a data connection port using either the PORT command or the PASV command. Sterling Connect:Enterprise assumes that the data connection uses the client's control connection port and the server's port adjacent to the control port (for example, L–1). Always specify the data connection port explicitly (through the PORT or PASV commands) instead of assuming the default. Sterling Connect:Enterprise FTP put Syntax The typical FTP client put and mput commands invoke the FTP server STOR command as shown in the following table. Required parameters are displayed in bold font. No optional parameters are available. 42 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Sterling Connect:Enterprise Variations from Standard FTP Commands FTP Command Sterling Connect:Enterprise FTP Server Command Syntax put, mput STOR Required. specifies the 1–64 character user batch ID of the batch to be added. User batch IDs can contain no wildcard characters, ('-', '.', '*', '?', '[', ']', '/', and '\'). Additionally, you cannot specify '#' as the first character. If more than 64 characters are specified, a command syntax error occurs. STOR Parameter Description put or mput Command (STOU) In Sterling Connect:Enterprise, the STOU command adds a batch to the current working data repository or the mailbox ID specified in the parameter. Set the current working mailbox ID using the FTP client cd command. Display the current working data repository using either the STAT command or the PWD command. For this command, the mailbox ID specified in overrides the setting of the current working mailbox ID, but does not change its value. Several parameters of the SITE command affect STOU processing. You can set these parameters using the SITE command and display them using either the STAT command or the PWD command. Several other parameters of the SITE command cause file characteristics to be stored with the batch. The following two security checks are made before the STOU command adds a batch: ✦ Session security exit call ✦ Security interface security checks The user batch ID returned by the STOU command is defined in the BID sub-parameter of the RECEIVE_OPTIONS of the remote's definition in the *REMOTES section of the ODF. If the BID sub-parameter is not specified, the user batch ID assigned is 'NONE'. The format of the user batch ID returned by the STOU command is: batch_ID.#nnnnnnn where batch_ID is the 1–64 character user batch ID, # is a constant, and #nnnnnnn is the 7-digit batch number with leading zeroes. A unique batch number is assigned to every batch that is added allowing Sterling Connect:Enterprise to support duplicate user batch IDs. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 43 Chapter 1 Sterling Connect:Enterprise FTP Implementation Note: Before issuing this command, specify a data connection port using either the PORT command or the PASV command. Sterling Connect:Enterprise assumes that the data connection uses the client's control connection port and the server's port adjacent to the control port (for example, L-1). For optimum performance, always specify the data connection port explicitly (through the PORT or PASV commands) instead of assuming the default Sterling Connect:Enterprise FTP put Syntax The typical FTP client put and mput commands invoke the FTP server STOU command. Required parameters are displayed in bold font. No optional parameters are available. FTP Command Sterling Connect:Enterprise FTP Server Command Syntax Parameter Description put, mput STOU No parameters are required. STOU pwd Command For Sterling Connect:Enterprise FTP the PWD prints the current working mailbox ID. It prints to your standard output. No security checks are made for the PWD command. pwd Command Syntax The typical FTP client pwd command invokes the FTP server PWD command as shown in the following table. Required parameters are displayed in bold font. No optional parameters are available. FTP Command Sterling Connect:Enterprise FTP Server Command Syntax Parameter Description pwd PWD None PWD cd Command The typical FTP client cd command invokes the FTP server CWD command. For Sterling Connect:Enterprise FTP the CWD command changes the current working mailbox ID to the specified value. The slash character (/) must precede the mailbox ID. Subsequent commands use the specified mailbox ID as the current working mailbox ID. The mailbox ID specified may or may not exist. Display the current working data repository using either the Stat command or the PWD command. 44 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Sterling Connect:Enterprise Variations from Standard FTP Commands Note: The values of 2 periods in a row (..) or a single period between two blank characters ( . ) are not supported and are treated as syntax errors. No security checks are made by this command. Authorization to use the specified mailbox ID is determined when an FTP server command attempts to access Sterling Connect:Enterprise. Note: Remote sites with the name “anonymous” are not permitted to use CWD. They are restricted to the “PUBLIC” mailbox ID. NLST Command For Sterling Connect:Enterprise FTP the NLST command lists user batch IDs in the current working data repository or the mailbox ID specified in the pathname parameter. For this command, the mailbox ID specified in pathname overrides the setting of the current working mailbox ID, but does not change its value. Set the current working mailbox ID using the FTP client cd command. Display the current working data repository using the STAT command or the PWD command. Note: The current data representation must be either ASCII or EBCDIC. Image type is unsupported and is not recognized. The SITE parameters BCHSEP, FTIME, LS_FILTER, ORIGIN, REMOTE_FILENAME_LENGTH, and TTIME affect NLST processing. You display these parameters using either the STAT command or the PWD command. The current data representation type value does not affect NLST processing. Unless LS_FILTER is used, output from NLST lists batches of any data type. Set the appropriate data type (ASCII or EBCDIC) before retrieving batches. The format of the list returned by the NLST command depends on the value of the BCHSEP parameter of the SITE command. See Batch Status Flags on page 41 for a description of these values. The following two security checks are made before the NLST command lists a batch: ✦ Session security exit call ✦ Security interface security checks Note: Before issuing this command, specify a data connection port (using either the PORT or PASV command). Sterling Connect:Enterprise assumes the data connection uses the client's control connection port and the server's port adjacent to the control port (for example, L–1). Always specify the data connection port explicitly (through the PORT or PASV commands) instead of assuming the default. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 45 Chapter 1 Sterling Connect:Enterprise FTP Implementation Sterling Connect:Enterprise NLST Command Syntax The typical FTP client ls, mdelete, and mget commands invoke the FTP server NLST command as shown in the following table. FTP Command Sterling Connect:Enterprise FTP Server Command Syntax Parameter Description pwd PWD NLST[ ] Optional. specifies the 1–64 character user batch ID of the batch to be listed. Batch Selection If the user batch ID specified in is in '#nnnnnnn', 'nnnnnnn', 'batch_ID.#nnnnnnn', or '#nnnnnnn.dat' format, and the batch is in the current working data repository, the single batch with batch number 'nnnnnnn' is eligible for the list. If the user batch ID specified in is in “generic-name”, 'specific', or 'spec*?[]' format, all of the batches in the current working data repository that match the user batch ID are eligible for the list. If the user batch ID is not specified, all of the batches in the current working data repository are eligible for the list. Eligible batches are selected for listing depending on the current settings of the SITE parameters FTIME, LS_FILTER, ORIGIN, and TTIME. An eligible batch is selected for listing if the following conditions are met: ✦ The batch is contained in an online VBQ. ✦ The batch's status is not excluded by the values specified in the LS_FILTER parameter. ✦ The batch's creation date and time is on or after the value specified in the FTIME parameter. ✦ The batch's creation date and time is on or before the value specified in the TTIME parameter. ✦ The batch's origination matches the value of the ORIGIN parameter or the ORIGIN parameter is blank. If eligible batches are available and selected, the list is returned through the data connection. If the user batch ID specified in is formatted as '#nnnnnnn', 'nnnnnnn', 'batch_ID.#nnnnnnn', or '#nnnnnnn.dat', the FTIME, LS_FILTER, ORIGIN, and TTIME parameters are ignored. The LS_FILTER parameter limits the selection of batches based on a batch's status flags. The FTIME and TTIME parameters limit the selection of batches based on the batch's earliest and latest creation date and time, respectively. The ORIGIN parameter limits the selection of batches based on the name of the user or remote that created the batch. 46 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Preparing Batches for the Sterling Connect:Enterprise FTP Server Preparing Batches for the Sterling Connect:Enterprise FTP Server The typical FTP client put and mput commands invoke the FTP server STOR or STOU command to add batches of data to the host data repository on the Sterling Connect:Enterprise FTP server. Scanning must be in effect on the Sterling Connect:Enterprise FTP server side for $$ADD commands to function as instructions to add batches of data to the VSAM batch files for transmission instead of being treated as data. If scanning is not in effect, all $$ADD and other embedded $$ commands as well as /* cards (/*SIGNON and /*BINASC, which contain session startup information) are treated as data. No $$ADD batches transferred by one FTP command are considered complete until the final $$ADD is complete. To continue scanning for additional $$ADD commands after each $$ADD command, you can use one of the following methods: ✦ At the FTP client site, include the parameter, SCAN=YES in each $$ADD command, or set the initial SCAN setting to ALL using the SITE command. ✦ At the FTP server site, set the initial SCAN setting to ALL in the ODF or by using the LOCSITE script command. When you embed $$commands in data, use the following table to determine how to delimit records, depending on the data structure, transfer mode, and data type. Data Structure Transfer Mode/Data Type End of Record Delimiter Record Stream Explicit End of Record (control code x’FF02’) File Block or Compressed EOR descriptor in block header (B) or Esc sequence (C) File Stream/ASCII Carriage Return-Line Feed (CRLF or x’0D0A’) File Stream/EBCDIC New Line (NL or ‘x15’) File Stream/Images Records not supported—only one $$ADD allowed and must be delimited by either: $$END with the rest of file being considered data 4096 bytes with data starting at the 4097th byte after the first $ in ADD. For more information about how $$ADD commands are processed and how Sterling Connect:Enterprise recordizes batches, see the chapter on configuring ODF records for FTP connections in the IBM Sterling Connect:Enterprise for z/OS Administration Guide. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 47 Chapter 1 Sterling Connect:Enterprise FTP Implementation Using $$Commands and /*Cards Files using embedded $$commands and /* cards must meet certain requirements. The first table summarizes these requirements for a file with a /*BINASC card; the second table is for a file without a /*BINASC card. In both tables, the file components are listed in the order of appearance in the file. The third column in both tables lists the character set for ASCII, Image, and EBCDIC data types. The character set can be ASCII (A), Scanning (S), and E (EBCDIC). When a record is scanned, its first byte determines the character set for that record: ✦ /*SIGNON, /*BINASC, $$ADD, $$DEL, $$DIR, $$LOG, $$REQ. ✦ Only look for /*SIGNON on first record. ✦ Only look for /*BINASC immediately after the first $$ADD. ✦ First check for EBCDIC then ASCII. The translate table used is specified in the TRANSLATE parameter in the *REMOTES record for FTP Client and server connections in the Options Definition File. This parameter specifies the name of the translation table to use when converting ASCII data to EBCDIC data or EBCDIC data to ASCII data. ✦ If no match for either type, data is assumed and is always binary. ✦ The last column, Ends with, lists the delimiter used to mark the end of the file: ✦ EOR stands for End of Record meaning the last byte of the record or $$END ✦ EOB stands for End of batch meaning the last byte of the batch ✦ EOF stands for End of File meaning the last byte of the file $$Commands and /*SIGNON with /*BINASC 48 File Component Specification Char Set for TYPE = A/I/E Begins at Ends with /*SIGNON Optional A/S/E First byte of file EOR First non-$$ADD $$command Optional A/S/E First byte of file or after /*SIGNON EOR Subsequent non-$$ADD $$commands Any number A/S/E After the previous non$$ADD $$cmd EOR First $$ADD command Optional A/S/E First byte of file or after the last present one of the preceding EOR /*BINASC Present in file A/S/E First byte of file or after the last present one of the preceding bytes After /*BINASC EOF First data Required Subsequent $$ADD and data Not allowed Binary IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Preparing Batches for the Sterling Connect:Enterprise FTP Server $$Commands and /*SIGNON without /*BINASC File Component Specification Char Set for TYPE = A/I/E Begins at Ends with /*SIGNON Optional A/S/E First byte of file EOR First non-$$ADD $$command Optional A/S/E First byte of file or after /*SIGNON EOR Subsequent non-$$ADD $$commands Any number A/S/E After the previous non$$ADD $$cmd EOR First $$ADD Optional A/S/E First byte of file or after the last present one of the preceding EOR /*BINASC Not present First data Required A / Binary / E First byte of file or after the last present one of the preceding EOF or EOB Subsequent $$ADD Any number A/S/E After last record of first data EOR Subsequent data Any number A/S/E After a subsequent $$ADD EOF or EOB Syntax The syntax for the $$ADD command at FTP sites is: $$ADD ID=xxxxxxxx BATCHID=‘xxx...xxx’ EO=N|NO|Y|YES MULTXMIT=N|NO|Y|YES SCAN=N|NO|Y|YES TO=N|NO|Y|YES VBQ#=n|nn XMIT=N|NO|Y|YES [$$END] Be sure to follow these rules: ✦ The first $ of the command must be the first character of a record. ✦ Use one or more blanks to separate each parameter. ✦ You must specify a BATCHID within a pair of single quotes. Otherwise, the parameter is not recognized. Once the string, BATCHID=’ is found, a corresponding close quote must be found within 24 bytes or the rest of the $$ADD card is ignored. ✦ Only ID and BATCHID values can have mixed case. All else must be upper case. Both unrecognized and duplicate parameters are ignored without generating any messages. Only the first parameter for each keyword is processed. $$ADD Command Parameters The following table describes the parameter that can be used with the $$ADD command at FTP client sites: IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 49 Chapter 1 Sterling Connect:Enterprise FTP Implementation Parameter Description ID=xxxxxxxx Optional. 1–8 bytes. BATCHID=’xx...xxx’ Optional. 1–64 bytes. Default for STOR or RETR is the BID. For STOU, it is taken from RECEIVE_OPTIONS BID parameter. If no BID parameter is specified, the STOU $$ADD BID defaults to 'BATCH WITHOUT $$ADD', not 'NONE'. A null BATCHID takes the default value, AC BATCH WITHOUT $$ADD. EO=N|NO|Y|YES Optional. Extract once. EO=YES specifies that the batch is extracted and stored one time from a remote client and cannot be transmitted. The default value EO=NO does not prevent transmission or multiple extractions. MULTXMIT=N|NO| Y|YES SCAN=N|NO|Y| YES Optional. Multi-Transmittable. The default is NO. Optional. Overrides current SCAN setting. The default is NO. Specifies whether Sterling Connect:Enterprise scans received batches for $$ commands. NO = Scanning for Sterling Connect:Enterprise $$ commands ends and the rest of the file is treated as data. YES = Scanning for Sterling Connect:Enterprise $$ commands continues. To keep scanning in effect when a $$ADD card is encountered, each $$ADD card must include the parameter SCAN=YES. Use this value to make FTP command scanning behave like it does in SNA. TO=N|NO|Y|YES Optional. Transmit once. TO=YES specifies that the batch being received can only be transmitted once and is not extractable. TO=YES can be thought of as “transmit once, transmit only“. The default TO=NO specifies that the batch is not marked non-transmittable. VBQ#=n|nn Optional. The default is the current collection VBQ. Specifies the number of the VBQ file on which batches collected in FTP sessions are to be stored. To set this value for multiple collections, the command is: LOCSITE VBQ#=nn KEEP KEEP must be the next parameter after VBQ#=nn to retain the value for more than one batch collection unless it part of an MGET command. If nn is 00, the assignment resets to the Current Collect VBQ. If nn is 01 through 20 that particular VBQ is allocated. XMIT=N|NO|Y|YES Optional. Transmittable. $$END 50 Optional for all files except for files with a File data structure transferred in stream mode containing images. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Chapter 2 Communicating with SNA Sites This chapter contains procedures and information specific to operating Sterling Connect:Enterprise with SNA sites. Start and End a Session The procedures for starting and ending a session are: 1. Establish a connection. Your remote site may exist on a switched (dialup) or nonswitched (dedicated or leased) line. You may have different procedures to follow when you first establish a connection with Sterling Connect:Enterprise. Get the specific procedures to establish a connection from your Sterling Connect:Enterprise system administrator. 2. Log on SNA. This procedure is done either manually or automatically and is remote-site dependent. 3. Type the commands described in this chapter. 4. Log off SNA. See Chapter 4, Remote User Commands for more information about logon and logoff functions for SNA. Host-Initiated Communications (Auto Connect) Sterling Connect:Enterprise has a function called Auto Connect that enables the host site computer to contact an unattended remote site. Using Auto Connect, Sterling Connect:Enterprise can both transmit to and collect data batches from remote sites. For Auto Connect to work, the remote site must appropriately respond to the host computer. Host site personnel provide the actions you take to prepare your site for responding to an Auto Connect from the host site. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 51 Chapter 2 Communicating with SNA Sites Sterling Connect:Enterprise is very flexible in the way it uses the Auto Connect function. For example, Sterling Connect:Enterprise can be configured to transmit batches to your remote site at different times throughout the night. Your remote site terminal or computer is then required to receive the batches whenever the host makes contact. Batches can be sent to the host site during Auto Connect. Since Auto Connect is often used with remote sites that can operate unattended, program or set up these terminals to send batches when the terminal is called by the host site. Alternatively, you may receive a call from the host site at certain times of the day. You can then manually send batches to the host, if instructed to do so. Host-initiated sessions do not support any $$ commands from the remote other than $$ADD. Using Sterling Connect:Enterprise Sterling Connect:Enterprise is a command-driven application. For example, a remote site can precede the transmittable data with a $$ADD header record. The following command tells Sterling Connect:Enterprise to add the data that follows to the host data repository and identify that batch as report summary from ACME: $$ADD ID=ACME BID=‘report summary’ The following command tells Sterling Connect:Enterprise to transmit all batches with an ID of ACME and a batch identifier of ‘report summary’ to the requesting remote site: $$REQUEST ID=ACME BID=‘report summary’ The following command tells Sterling Connect:Enterprise to flag as deleted all batches with an ID of ACME and a batch identifier of ‘report summary’: $$DELETE ID=ACME BID=‘report summary’ Wildcard Characters in Sterling Connect:Enterprise Names Sterling Connect:Enterprise, SPC Option 3.1, and IBM® Sterling Connect:Enterprise® for UNIX 3.1 use the following special characters as wildcard characters when making decisions for various 52 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Terminal-Dependent Options types of data repository processing. Use the following wildcard characters in selection checks, most notably with BID values. Wildcard Character Function asterisk (*) Indicates any number of characters question mark (?) Indicates a single character square brackets ([ ]) with any number of characters inside the brackets including an exclamation mark (!) Indicates a specific character, or characters within a string of characters. You may create batches with a BID value that include wildcard characters. However you may get unexpected results if you use wildcard characters in requests. For example: ✦ You create three batches with a BID value of ‘Test **’, ‘Test 123’, and ‘Test **456’ respectively. Because offline ADD processing and online collection processing do not restrict putting wildcard characters in the BID parameter, the batches are added to Sterling Connect:Enterprise without errors. ✦ To collect the batch with the BID of ‘TEST **’ you create the following $$REQUEST card: $$REQ ID=yourid BID=’TEST **’ ✦ After submitting the request, you discover that you have collected data from all three batches. To prevent the previous error, take one of the following steps: ✦ Refrain from using the wildcard characters when defining any name in data repository. The Sterling Connect:Enterprise System Administrator can enforce this rule by creating a Security Exit 1 and Offline ADD Exit to restrict the use of these characters in name values when adding data. ✦ Continue to use wildcard characters in data repository name values, but do not use any parameters that support wildcard characters. For example, use the #nnnnnnn parameter to request a specific batch by number. Do not use BID=‘xxx-xxx’, as this parameter supports wildcards. Using this method limits selection, but eliminates confusion. Terminal-Dependent Options A variety of terminals and devices can communicate with Sterling Connect:Enterprise, but they do not all have the same capabilities. For this reason, Sterling Connect:Enterprise supports some terminal-dependent options for SNA. Some of these options are used only if they are installed by host site personnel. Other options do not require host site installation; they are used if your terminal type supports them. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 53 Chapter 2 Communicating with SNA Sites SNA Sites SNA terminal-dependent options are enabled only if your remote terminal supports the capability. These options include: ✦ Multiple Logical Unit (MLU) support ✦ Device media support ✦ Console display use ✦ Data compression ✦ Batch separation using Function Management Headers (FMHs) ✦ SNA transparency ✦ Disconnect interval ✦ Extended Binary Coded Decimal Information Code (EBCDIC) support Detailed information about these options is provided in the sections that follow: MLU (Multiple Logical Unit) Support MLU Support permits a single remote terminal to be considered up to six terminals or sessions. Each session can have a different transaction in progress with Sterling Connect:Enterprise for a mixture of simultaneous data collections or transmissions on each of the separate terminals. Type a logon command to Sterling Connect:Enterprise for each MLU session you wish to activate. These sessions are used as pipelines to activate multiple inbound and outbound data streams that all come from the same remote site. Alternatively, think of these sessions as logical remotes, with each remote site appearing as a separate remote to Sterling Connect:Enterprise. It is possible to let your remote terminal have one or more active sessions with Sterling Connect:Enterprise, along with active sessions to other applications in the host, such as JES2. All these options depend on the implementation of MLU capabilities in your remote terminal. Sterling Connect:Enterprise automatically handles the MLU capability if it receives more than one logon for the same remote site. To implement MLU support: 1. Find out if and how your remote terminal supports MLU. 2. Logon multiple times to Sterling Connect:Enterprise. 3. Use any active MLU session to send or receive data. Device Media Support Some terminals have the capability to send or receive data on a certain medium. You can send data to Sterling Connect:Enterprise from the following media: ✦ Console keyboard ✦ Card reader ✦ Exchange disk (transmission format or basic exchange) ✦ Printer output 54 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Terminal-Dependent Options You can receive data from Sterling Connect:Enterprise to the following media: ✦ Console display ✦ Card punch ✦ Exchange disk (transmission format or basic exchange) ✦ Printer You always control the medium for inbound data sent to Sterling Connect:Enterprise. The medium used for outbound data sent to your terminal is controlled by you or by defaults set by host site personnel when Sterling Connect:Enterprise is installed. When you request a batch from Sterling Connect:Enterprise, specify the medium that receives data from Sterling Connect:Enterprise. If you do not specify the medium, the batch is sent to the default medium for your remote site, as selected by host site personnel. To implement device media support: 1. Determine if your remote terminal supports the receipt of data to a variety of media. 2. Ask your host site personnel to set a certain default medium for your remote site. 3. Specify the medium used when you request data from Sterling Connect:Enterprise, if different from the default. (optional) Console Display Use Sterling Connect:Enterprise can direct specific short information messages or error messages to a console display screen if your remote site is set up to handle the messages. Some types of messages are: ✦ A message following a successful logon to Sterling Connect:Enterprise ✦ A message indicating that Sterling Connect:Enterprise is ready to receive data from your terminal ✦ A message following a security violation These messages are very helpful, so use them whenever possible. In order for Sterling Connect:Enterprise to send the messages, your host site personnel must set an option for your remote site before Sterling Connect:Enterprise is brought online. To implement console display: 1. Find out if your remote terminal can display control messages or other data on a console. 2. Ask host site personnel to define your remote site as a console device. This is the default value. Data Compression If your device cannot receive data from Sterling Connect:Enterprise in a compressed format, personnel at the host site need to know so they can specify COMPRESS=NO in the ODF. In addition, ensure the host VTAM Logon Mode Table reflects that compression is not supported. If these two areas are in conflict, message CMB184I is issued on the host system console. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 55 Chapter 2 Communicating with SNA Sites Batch Separation Using FMHs Remote sites can sometimes insert Functional Management Headers (FMHs) at the beginning and end of a batch sent to Sterling Connect:Enterprise. Your terminal probably controls the use of FMHs, and you need not worry about them. Some terminals enable you to influence the insertion of these FMHs, thereby indicating what is considered a batch to Sterling Connect:Enterprise. If your terminal has this capability, Sterling Connect:Enterprise automatically supports it. You have the option to control when the FMHs are used, or you may configure this Process to run in the background. If your terminal or the software package used on your terminal mentions FMHs, ensure your use of FMHs is compatible with Sterling Connect:Enterprise. Sterling Connect:Enterprise assumes that an FMH for Begin Data Set (BDS) marks the beginning of a batch, and an FMH for End Data Set (EDS) marks the end of a batch. If you are sending a single batch to Sterling Connect:Enterprise, this is probably handled automatically. If you are sending multiple batches or using nested send functions, your terminal may or may not separate the batches with FMHs. If you want Sterling Connect:Enterprise to consider the multiple batches as separate, you must ensure FMHs are inserted. To implement batch separation using FMHs: 1. Determine if you have any control over the insertion of FMHs. This control influences what constitutes a batch to Sterling Connect:Enterprise. 2. No host site installation option is needed. Sterling Connect:Enterprise automatically handles FMHs if present. SNA Transparency SNA transparency enables Sterling Connect:Enterprise to send and receive data that contains special embedded control characters, such as object modules. This function is often needed when sending data from a remote personal computer to the host site, but the data is not converted from ASCII to EBCDIC. Sterling Connect:Enterprise automatically supports the use of SNA transparency with two restrictions: ✦ Outbound data from Sterling Connect:Enterprise to your terminal does not use transparency for data sent to the printer media or to the basic exchange media. ✦ Sterling Connect:Enterprise cannot recognize control commands that are sent as transparent data and not converted to EBCDIC transmission code. To implement SNA transparency: 1. Choose the appropriate method for your terminal type to send transparent data to Sterling Connect:Enterprise. 2. No host site installation option is needed. Sterling Connect:Enterprise automatically handles transparent data. 56 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Sample Data Streams Disconnect Interval The disconnect interval forces your session with Sterling Connect:Enterprise to terminate when your session is inactive for a certain time interval. The function of the Sterling Connect:Enterprise disconnect interval is to: ✦ Reduce phone costs in a dial-up network ✦ Provide added security Host site personnel implement remote Sterling Connect:Enterprise disconnect intervals and define time intervals, which are from 1-9 seconds, 999 seconds, or set to 0 to prevent any forced disconnect. If your remote site has a similar function, set a different disconnect interval than that used by Sterling Connect:Enterprise. For information about setting a different disconnect interval, contact your host site system administrator. Note: If you lose your connection to Sterling Connect:Enterprise while transmitting data, the cause is probably a network issue rather than the expiration of the disconnect interval. EBCDIC Support Sterling Connect:Enterprise can receive any data format, but can only interpret data that uses EBCDIC character code. Sample Data Streams The following are samples of valid data streams sent from a remote site to Sterling Connect:Enterprise: 1. At SNA sites, request a directory listing of all batches associated with mailbox ID BRANCH01 and send in two files containing data for a payroll job run at the host. $$DIRECTORY ID=BRANCH01 $$ADD ID=BRANCH01 BATCHID=‘4/23 PAYROLL DATA’ SCAN=Y data record 1 data record 2 . . last data record $$ADD ID=BRANCH01 BATCHID=‘4/24 PAYROLL DATA’ SCAN=N data record 1 data record 2 . . last data record IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 57 Chapter 2 Communicating with SNA Sites Note: Because the $$ADD commands are processed first, the newly added batches are included in the $$DIRECTORY output. 2. Request three data transmissions from the host: one for all batches waiting for transmission to mailbox ID BRANCH01, and two for specific batches for mailbox ID MARY. Data requested for mailbox ID MARY is sent directly to a printer. $$REQUEST $$REQUEST $$REQUEST ID=BRANCH01 ID=MARY BATCHID=‘LETTER FROM JOE’ ID=MARY BATCHID=#14 MEDIA=PR MEDIA=PR 3. For SNA sites the MEDIA operand is added so that the directory list is displayed on the console display. $$DELETE $$DIRECTORY ID=MARY BATCHID=#67 PASSWORD=SECRET MEDIA=CN SNA Site Parameters The following table describes the SNA site parameters: Operand Command Description APPLID(xxxxxxxx) LOGON The 1–8 character APPLID given to Sterling Connect:Enterprise at the host site, as chosen by your host site personnel. LOGOFF $$LOGOFF BCHSEP=OPT3 $$REQUEST Separates batches sent to remote sites when sending multiple batches in a single connection. OPT3 BCHSEP must remain consistent throughout a single connection and all $$ commands. DATA(XXX,,XXX) 58 LOGON Supplies your remote name to Sterling Connect:Enterprise. Host site personnel supply you with your own unique, confidential remote name. If required, you may supply a password (separated from the remote name by two commas) and use the new password option. This information resides in the logon, because it determines some options to use during communications. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide SNA Site Parameters Operand Command Description EO=N | Y $$ADD Specifies that the batch is extracted only once and cannot be transmitted. After extraction, the batch is permanently locked. FORMAT=BID24 | BID64 $$DIRECTORY Specifies the format to use when listing batches. BID24 displays the directory using the first 24 characters of the User Batch ID. BID64 displays the directory display using the full 64 characters of the User Batch ID. LOGMODE(xxxxxxxx) LOGON Supplies a value to determine the rules for communications between Sterling Connect:Enterprise and your remote site. It is a 1-8 character name, as chosen by your host site personnel. MEDIA=CN | PR | PU | EX | BX $$DIRECTORY (SNA sites only.) This parameter asks the host $$REQUEST site to send the output data to the specified media on the remote device. Your remote device must support the requested media, ensure the media is ready and available for use. CN sends output data to the console display. This option causes Sterling Connect:Enterprise to use an X‘15’ (new line) as a record separator. PR sends output data to the printer. This option causes Sterling Connect:Enterprise to use an X‘15’ (new line) as a record separator. PU sends output data to the card punch. This option causes to use an X‘1E’ (standard IRS) as a record separator. EX sends output data to the exchange disk, and uses transmission exchange format. BX sends output data to the exchange disk, and uses basic exchange format. Many remote devices have the capability to assign media. For example, output data sent to the card punch is often assigned to a disk file on a personal computer. Sterling Connect:Enterprise is not aware of how you assign your remote site’s media. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 59 Chapter 2 Communicating with SNA Sites Operand Command Description MULTXMIT=NO | YES $$ADD (MX=) NO indicates that the batch is not available for multiple transmission. If a batch marked NO transmits to a remote site, that batch is marked with a T and is not available for transmission unless requested by batch number. YES indicates that the batch is available to all remote sites and is not marked with a T when requested by and transmitted to a remote site. Note: When MULTXMIT=YES, XMIT is forced to YES. ONEBATCH=NO | YES $$REQUEST (OB=) NO indicates all matching batches are returned. YES indicates that when BATCHID= is specified, only the first matching batch is returned. PASSWORD=xxxxxxxx $$DIRECTORY (PSWD=) The PASSWORD, if used, must match that supplied by host personnel for the Sterling Connect:Enterprise system. This parameter is required if the ID parameter is omitted. RMT=xxxxxxxx LOGOFF Replace the xxxxxxxx with the 1-8 byte remote name assigned to your remote terminal. It must match the remote name supplied in the logon. This operand is required. $$LOGOFF SCAN=NO | YES $$ADD NO indicates that all $$ commands must begin at the start of a data block. The default is NO. YES indicates that each record of each data block is decompressed and deblocked to SCAN for embedded $$ commands. This removes the requirement for starting $$ commands at the beginning of a data block. Use of this operand could result in system degradation due to the increased overhead. Note: Specifying SCAN=YES causes Sterling Connect:Enterprise to scan for only the next $$ command in subsequent data blocks. Once the next $$ command is found, further scanning is controlled by repeated specification of the SCAN= parameter. Note: The SCAN=YES facility for the $$ADD control card is ignored on remote sites that have SC=YES defined in the *REMOTES record in the ODF. TO=N | Y 60 $$ADD Specifies that the batch is not extracted. It permits only one successful transmission, then the batch is permanently locked. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide SNA Site Parameters Operand Command Description TRUNC=NO | YES $$REQUEST This parameter specifies whether Sterling Connect:Enterprise truncates all trailing blanks from records before data transmission. NO means no blanks are truncated. YES means all blanks are truncated prior to data compression and data transmission. VBQ#=xx $$ADD IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Specifies the VBQxx (where xx is any number from 1-20) file where you want to add the batch. If this option is not specified, the batch is placed in the current collection VBQ file. If the specified VBQ is not allocated, the batch is added to the current collection VBQ. 61 Chapter 2 Communicating with SNA Sites Operand Command Description WAIT=hh:mm:ss, C $$REQUEST Specifies the maximum Sterling Connect:Enterprise wait time and retry cycle used for the $$REQUEST. Permits the remote site to wait for transmittable batches for a specified time if no batches are initially found. The wait time is specified in hours, minutes, and seconds. The following describes valid values for the first subparameter: ss— Specifies the amount of time to wait, in seconds. The maximum allowable value in this form is 59. mm:ss—Specifies the amount of time to wait, in minutes and seconds. The maximum allowable value in this form is 59:59. hh:mm:ss—Specifies the amount of time to wait, in hours, minutes, and seconds. The maximum allowable in this form is 23:59:59. The second parameter is optional. It specifies the number of wait and retry cycles to attempt before failing the request if no batches are available. The maximum allowable value is 999. The default value is 1. For example, use the following to request all batches for an ID and to specify the wait period, if no batches are found: $$REQUEST ID=DALLAS WAIT=59,10 This request waits 59 seconds for a transmittable batch and retries the search for a transmittable batch 10 times. This effectively waits for a batch for a total of 9 minutes and 50 seconds. Once a request is satisfied by sending one or more batches, the request is removed from the wait loop. If all retries are done and no batches are available for transmission, then the standard message of no batches for transmission is sent to the remote site. Note: If your SNA session is through SPC, verify that the disconnect interval defined in SPC is adequate to support appropriate processing. XMIT=NO |YES $$ADD NO indicates that the batch is available only to the host site. YES indicates that the batch being sent to the host is available for transmission to any remote site that requests it with the appropriate mailbox ID. 62 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide SNA Site Parameters IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 63 Chapter 2 Communicating with SNA Sites 64 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Chapter 3 Communicating with BSC Sites This chapter contains procedures and information specific to operating Sterling Connect:Enterprise with BSC sites. Start and End a Session The specific procedures for starting and ending a session are: 1. Establish a connection. Your remote site may exist on a switched (dialup) or nonswitched (dedicated or leased) line. You may have different procedures to follow when you first establish a connection with Sterling Connect:Enterprise. Get the appropriate procedures to establish a connection from your Sterling Connect:Enterprise system administrator. 2. SIGNON (optional). This procedure is done either manually or automatically and is remote-site dependent. 3. Type the commands described in this chapter. Sterling Connect:Enterprise Support for Signon (BSC Sites) Remote terminals that communicate with Sterling Connect:Enterprise are often designed to communicate with special RJE (Remote Job Entry) systems on the host computer, such as JES. Some RJE systems require a SIGNON record sent from the remote site when the transmission connection is established. Sterling Connect:Enterprise does not require this SIGNON record, but can accept it if your remote terminal sends it to the host site. Sterling Connect:Enterprise is configurable to permit a free-form SIGNON record, which is received by the host from your remote but is not validated. The host site personnel who install Sterling Connect:Enterprise define one or more valid SIGNON records, and inform the remote sites of the appropriate data to use. Sterling Connect:Enterprise does not require the fixed-form SIGNON record. Begin your input data with any of the Sterling Connect:Enterprise $$ commands other than the SIGNON. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 65 Chapter 3 Communicating with BSC Sites Host site personnel can also define optional free-form SIGNON records that create an environment for security checking. Coordinate the use of this or other SIGNON support with the host site. Host-Initiated Communications (Auto Connect) Sterling Connect:Enterprise has a function called Auto Connect that enables the host site computer to contact an unattended remote site. Using Auto Connect, Sterling Connect:Enterprise can both transmit to and collect data batches from remote sites. For Auto Connect to work, the remote site must appropriately respond to the host computer. Host site personnel provide the actions you take to prepare your site for responding to an Auto Connect from the host site. Sterling Connect:Enterprise is very flexible in the way it uses the Auto Connect function. For example, Sterling Connect:Enterprise is configurable to transmit batches to your remote site at different times throughout the night. Your remote site terminal or computer is then required to receive the batches whenever the host makes contact. Batches can be sent to the host site during Auto Connect. Since Auto Connect is often used with remotes that can operate unattended, program or set up these terminals to send batches when the terminal is called by the host site. Alternatively, you may receive a call from the host site at certain times of the day. You can then manually send batches to the host, if instructed to do so. Host-initiated sessions do not support any $$ commands from the remote other than $$ADD. Using Sterling Connect:Enterprise Sterling Connect:Enterprise is a command-driven application. For example, a remote site can precede the transmittable data with a $$ADD header record. The following command tells Sterling Connect:Enterprise to add the data that follows to the host data repository and identify that batch as report summary from ACME: $$ADD ID=ACME BID=‘report summary’ The following command tells Sterling Connect:Enterprise to transmit all batches with an ID of ACME and a batch identifier of ’report summary’ to the requesting remote site: $$REQUEST ID=ACME BID=‘report summary’ The following command tells Sterling Connect:Enterprise to flag as deleted all batches with an ID of ACME and a batch identifier of ’report summary’: $$DELETE ID=ACME BID=‘report summary’ 66 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Wildcard Characters in Sterling Connect:Enterprise Names Wildcard Characters in Sterling Connect:Enterprise Names Sterling Connect:Enterprise, SPC Option 3.1, and Sterling Connect:Enterprise for UNIX 3.1 use the following special characters as wildcard characters when making decisions for various types of data repository processing. Use the following wildcard characters in selection checks, most notably with BID values. Wildcard Character Function asterisk (*) Indicates any number of characters question mark (?) Indicates a single character square brackets ([ ]) with any number of characters inside the brackets including an exclamation mark (!) Indicates a specific character, or characters within a string of characters. You may create batches with a BID value that include wildcard characters. However you may get unexpected results if you use wildcard characters in requests. For example: ✦ You create three batches with a BID value of ’Test **’, ’Test 123’, and ’Test **456’ respectively. Because offline ADD processing and online collection processing do not restrict putting wildcard characters in the BID parameter, the batches are added to Sterling Connect:Enterprise without errors. ✦ To collect the batch with the BID of ’TEST **’ you create the following $$REQUEST card: $$REQ ID=yourid BID=’TEST **’ ✦ After submitting the request, you discover that you have collected data from all three batches. To prevent the previous error, take one of the following steps: ✦ Refrain from using the wildcard characters when defining any name in data repository. The Sterling Connect:Enterprise System Administrator can enforce this rule by creating a Security Exit 1 and Offline ADD Exit to restrict the use of these characters in name values when adding data. ✦ Continue to use wildcard characters in data repository name values, but do not use any parameters that support wildcard characters. For example, use the #nnnnnnn parameter to request a specific batch by number. Do not use BID=’xxx-xxx’, as this parameter supports wildcards. Using this method limits selection, but eliminates confusion. Terminal-Dependent Options A variety of terminals and devices can communicate with Sterling Connect:Enterprise, but they do not all have the same capabilities. For this reason, Sterling Connect:Enterprise supports some terminal-dependent options for BSC remote sites. Some of these options are used only if they are IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 67 Chapter 3 Communicating with BSC Sites installed by host site personnel. Other options do not require host site installation; they are used if your terminal type supports them. BSC Options BSC terminal-dependent options are used only if your remote terminal supports them. These options include: ✦ Free-form BSC SIGNON ✦ Blank compression ✦ Blank truncation ✦ Blocked data records ✦ BSC transparency ✦ Record separator override ✦ Use of $TURNLINE$ ✦ Temporary Text Delay (TTD) ✦ Wait acknowledgement (WACK) Detailed information about these options is provided in the sections that follow: Free-Form BSC SIGNON This SIGNON requires a remote name and an optional password. It is optional and must be coordinated with the Sterling Connect:Enterprise host site system administrator. BSC SIGNON permits users to identify themselves as a specific remote. Without this SIGNON, users are identified only by the line on which they connected. This line is typically shared by other users and does not provide a unique identification. For more information on the free-form BSC SIGNON, refer to the Defining the ODF chapter in the IBM Sterling Connect:Enterprise for z/OS Installation Guide. Blank Compression Data sent over telecommunications systems may contain many blanks (spaces). By using the blank compression method defined for the IBM 3780 data communication terminal, Sterling Connect:Enterprise can remove four or more contiguous blank spaces and replace them with a control character that indicates the number of compressed blanks. In order to specify blank compression to Sterling Connect:Enterprise in a transmission request, the remote terminal must also use the IBM 3780 method. In addition, both the host and the remote sites must use blank compression/decompression for a given transmission or the data is invalid. A batch collected using blank compression is stored in the VSAM batch files in compressed form and is automatically decompressed by the EXTRACT utility when extracted from the data repository. 68 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Terminal-Dependent Options Blank Truncation Text data sent over telecommunications systems may have a large number of blanks at the end of each record. Sterling Connect:Enterprise can remove trailing blanks from records sent to remote sites. If the trailing blanks are necessary, the remote site must have the capability to replace them. Also, Sterling Connect:Enterprise can accept data with the trailing blanks stripped. Blank truncation is restricted to 80-byte fixed-length records. Sterling Connect:Enterprise assumes blank truncated records are 80-byte fixed-length and a control character indicating the number of blanks removed is not required. Blocked Data Records It is more efficient to transmit blocks of data containing multiple records than it is to transmit individual records. Sterling Connect:Enterprise sends and receives blocked data records. However, the block size must not exceed 4096 bytes. If a record does not fit into a block, it is sent in the next block. An Inter-Record Separator (IRS) X’1E’ or Inter-Unit-Separator (IUS) X’1F’ must separate the records. X‘1E’ is the most commonly used and is the system default for an IRS. The record separator used by Sterling Connect:Enterprise when transmitting is set by the host site personnel for each BTAM transmission line at system installation. All terminals using the same line must handle the record separator sent by the host. If the terminals cannot handle the record separator sent by the host, the remote site must use the Record Separator Override option. Note: All data, including record separators and BSC control characters (for example, STX (X‘02’), ETX (X‘03’), and so forth), must fit in the block size. This is the BUFSIZ= value in the M$LINE user assembly defined at the host site. Blocked data collected by Sterling Connect:Enterprise is stored in the VSAM batch files in blocked form. The EXTRACT utility automatically deblocks the blocked data while extracting it from the data repository. BSC Transparency Sterling Connect:Enterprise is capable of sending and receiving transparent data. Transparent data can contain embedded line control characters. BSC transparency is often a hardware function on terminals and is invoked by setting a switch. When Sterling Connect:Enterprise receives a $$REQ from a remote site in transparency form, it transmits all return data in transparency form. Refer to your terminal or computer operation manual to determine the action required to use BSC Transparent Data Transmission. Record Separator Override A Record Separator (control character) separates multiple records sent in a single nontransparent block. A default IRS is set by the host site personnel for each line used by Sterling Connect:Enterprise. If a remote site cannot process the default record separator, the site may request a record separator override when it asks for data from Sterling Connect:Enterprise. The record separator is typically either X‘1E’ or X‘1F.’ IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 69 Chapter 3 Communicating with BSC Sites Use of $TURNLINE$ The $TURNLINE$ capability provides a special method of limited conversational transmissions between your remote site and Sterling Connect:Enterprise at the host site. Instead of the standard send all-receive all mode of communications, your remote site can send-receive-send-receive-send-receive, and so on, as done for conversational transmissions. To use this option, coordinate the send-receive sequence exactly with the data batch being sent from the host site. You send your terminal a signon record, receive data from your terminal, then send data to your terminal. In this case, set up your terminal to receive the signon record, send data to the host site, then receive data from the host site. Changing from receive to send, and vice versa, is called a line turnaround. The host site data batch being sent controls when the line turnaround occurs. The data batch must contain a $TURNLINE$ record. When the host site detects a $TURNLINE$ record, it stops sending and does a line turnaround to receive. The $TURNLINE$ record is not sent to the remote site. After the receive is complete, the host site can again do a line turnaround to send. Carefully coordinate the use of this option with the host site. If the $TURNLINE$ feature is used, get any special requirements for its implementation from the host site personnel. Temporary Text Delay (TTD) Sterling Connect:Enterprise sends a BSC 3780 TTD to remotes when file I/O requires more than a set period of time to complete (usually 3 seconds). TTD processing is invoked when Sterling Connect:Enterprise is searching for a transmittable batch or when flagging batches matching the Auto Connect listname as transmitted. The format of the TTD is STX ENQ or X‘022D’. The remote must reply with a BSC NAK X‘3D’. WAIT Acknowledgement (WACK) Sterling Connect:Enterprise is capable of handling a variable number of WACKs (X’106B’) from a remote site while waiting for the transmission to continue. Sterling Connect:Enterprise responds with the appropriate ENQ (X’2D’) until the limit, which is controlled by the WACKMAX ODF parameter, is reached. If you find that Sterling Connect:Enterprise disconnects before your remote continues transmission, contact host site personnel about increasing the WACKMAX value. Sample Data Streams The following are samples of valid data streams sent from a remote site to Sterling Connect:Enterprise: 1. At BSC sites, request three data transmissions from the host: one for all batches waiting for transmission to mailbox ID BRANCH02, and two for specific batches for mailbox ID MARY. Data requested for mailbox ID MARY is sent compressed, and all data is sent in blocks of six records each. $$REQUEST $$REQUEST $$REQUEST 70 ID=BRANCH02 BLOCK=6 ID=MARY BATCHID=‘LETTER FROM JOE’ BLOCK=6 CMP=Y ID=MARY BATCHID=#0014 BLOCK=6 CMP=Y IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Sample Data Streams 2. Request Sterling Connect:Enterprise to delete a batch for mailbox ID MARY and send a directory listing of all batches for all mailbox IDs on the VSAM batch files. $$DELETE $$DIRECTORY ID=MARY BATCHID=#0067 PASSWORD=SECRET BSC Site Parameters The following table describes the BSC site parameters. Operand Command Description BCHSEP=NO | OPT1 | OPT2 | OPT3 $$DELETE Specifies the method Sterling Connect:Enterprise uses to separate the data for multiple $$ commands. $$DIRECTORY $$REQUEST NO indicates batches are not separated. If multiple batches are sent in a single connection, they are concatenated and sent as a single batch. Ensure remote sites using this line can process concatenated data batches if this option is chosen. OPT1 causes Sterling Connect:Enterprise to use a common RJE method of separating batches. At the end of each batch, Sterling Connect:Enterprise sends an EOT (x’37’) to the remote, reads a response from the remote, and then sends ENQ (x’02’)to request use of the line. Do not use OPT1 if the remote site using this line cannot appropriately respond to this protocol. OPT2 Sterling Connect:Enterprise separates batches using an ETX (X‘03’). Do not use OPT2 unless the remote can appropriately respond to this protocol. BCHSEP must remain consistent throughout a single connection and all $$ commands. BLOCK=xx $$DIRECTORY $$REQUEST The BLOCK operand prompts Sterling Connect:Enterprise to send multiple records in a single data block, separated by control characters. xx–specifies the number of records sent per block, up to a maximum of 99. If BLOCK is omitted, the records are transmitted to the remote site unblocked. To use this operand, a remote site terminal must be capable of deblocking the records for use at the remote site. If the BLOCK factor specified causes Sterling Connect:Enterprise to build a block that is larger than the maximum buffer size (4096), a smaller blocking factor forces the specific transmission size. $$END $$ADD The $$END parameter signifies the end of a $$ADD card. It is valid only for blocked BSC transparent transmissions. The $$END characters are the last five bytes of the $$ADD record. EO=N | Y $$ADD Specifies that the batch is extracted only once and cannot be transmitted. After extraction, the batch is permanently locked. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 71 Chapter 3 Communicating with BSC Sites Operand Command Description FORMAT=BID24 | BID64 $$DIRECTORY Specifies the format to use when listing batches. BID24 displays the directory using the first 24 characters of the User Batch ID. BID64 displays the directory display using the full 64 characters of the User Batch ID. MULTXMIT=NO | YES $$ADD (MX=) NO indicates that the batch is not available for multiple transmission. If a batch marked NO transmits to a remote site, that batch is marked with a T and is not available for transmission unless requested by batch number. YES indicates that the batch is available to all remote sites and is not marked with a T when requested by and transmitted to a remote site. Note: When MULTXMIT=YES, XMIT is forced to YES. ONEBATCH=NO | YES $$REQUEST (OB=) NO indicates all matching batches are returned. PASSWORD= xxxxxxxx $$DIRECTORY (PSWD=) The PASSWORD, if used, must match that supplied by host personnel for the Sterling Connect:Enterprise system. This parameter is required if the ID parameter is omitted. RECSEP=1E | 1F $$DIRECTORY Temporarily overrides the assigned line Record Separator that sends blocked records from the host site. YES indicates that when BATCHID= is specified, only the first matching batch is returned. $$REQUEST Either 1E or 1F is specified as the record separator. TO=N | Y $$ADD Specifies that the batch is not extracted. It permits only one successful transmission, then the batch is permanently locked. TRUNC=NO | YES $$REQUEST This parameter specifies whether Sterling Connect:Enterprise truncates all trailing blanks from records before data transmission. NO means no blanks are truncated. YES means all blanks are truncated prior to data compression and data transmission. VBQ#=xx $$ADD Specifies the VBQxx (where xx is any number from 1-20) file where you want to add the batch. If this option is not specified, the batch is placed in the current collection VBQ file. If the specified VBQ is not allocated, the batch is added to the current collection VBQ. XMIT=NO | YES $$ADD NO indicates that the batch is available only to the host site. YES indicates that the batch being sent to the host is available for transmission to any remote site that requests it with the appropriate mailbox ID. 72 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Chapter 4 Remote User Commands This chapter describes the following commands available to Sterling Connect:Enterprise remote users.: ✦ $$ADD sends a batch of data to the host site ✦ $$DELETE flags a batch of data, as deleted, at the host site ✦ $$DIRECTORY requests a formatted listing of batches from the host site ✦ $$LOGOFF logs off from Sterling Connect:Enterprise at the host site ✦ $$REQUEST requests a batch of data from the host site In addition, this chapter gives session information and user instructions to assist you during a Sterling Connect:Enterprise session. Submit Commands When a remote connection is established, the remote site communicates with Sterling Connect:Enterprise by means of the command utilities, referred to as the $$ commands. These commands are described in the following sections. The $$ADD command is the only command available for a remote site when the connection is initiated by the host using an Auto Connect. $$REQUEST, $$DIRECTORY, $$DELETE, and $$LOGOFF (SNA only) are typed in these three ways: ✦ Individual commands from your remote computer console keyboard or from a data file ✦ Commands before a $$ADD record at the start of a data batch ✦ Commands after a $$ADD record with SCAN=Y (SNA sites) When the host receives $$ commands that precede $$ADD, they are saved and processed in the order received after all inbound data for the $$ADD is received. When the host receives $$ commands as single commands that do not precede $$ADD, they are processed immediately and the output data is sent to your remote site. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 73 Chapter 4 Remote User Commands For BSC only, if multiple $$ output commands are received, the output data is sent as batches separated by EOTs (X’37’) (see BCHSEP=OPT1 on page 3-11). If a remote site is unable to use this method of batch separation, the remote must specify BCHSEP=OPT2 on each $$ output command line. This separates batches with an ETX (X’03’). The following rules apply to $$ commands: ✦ Place the $$ command in column 1. ✦ Code any number of blanks between operands. ✦ Do not use commas between operands. ✦ Type commands and operands in upper case. ✦ Code must be EBCDIC. ✦ Code each parameter value as documented in Chapter 3, Communicating with BSC Sites. Short forms are not allowed. ✦ Do not exceed the maximum record length. The maximum $$ remote command record length is 100 for BSC and 256 for SNA. The following worksheets can assist you in typing information pertinent to the $$ commands. The worksheets can be duplicated and used routinely. 74 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Submit Commands $$ Command Worksheet Command $$ADD | $$DELETE | $$DIRECTORY | LOGON | $$LOGOFF | $$REQUEST Remote site IDs Contact your host site administrator for the following remote site IDs. Mailbox ID: ID=_______________________________ User Batch ID: BATCHID=__________________________________________ Circle the appropriate option or contact you host site administrator for the values required for the following operands. SNA Options BSC Options Operand Value Operand Value BCHSEP = OPT3 BCHSEP = NO | OPT1 |OPT2 | OPT3 EO =N|Y EO =N|Y FORMAT = BID24 | BID64 FORMAT = BID24 | BID64 MEDIA = CN | PR | PU | EX | BX CMP = NO | YES MULTXMIT = NO | YES MULTXMIT = NO | YES ONEBATCH = NO | YES RECSEP = NO | YES SCAN = NO | YES TO =N|Y TO =N|Y TRUNC = NO | YES TRUNC = NO | YES XMIT = NO | YES WAIT = hh:mm:ss, C __________________ BLOCK =______________________ XMIT = NO | YES PASSWORD =______________________ APPLID =____________________ VBQ# =______________________ DATA =____________________ LOGMODE =____________________ PASSWORD =____________________ RMT =____________________ IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 75 Chapter 4 Remote User Commands $$ADD Command $$ADD places batches of data into the data repository, and precedes the batch data that is sent. You may send any number of $$ADD records and associated data files to the host site. The data collection function is initiated by the remote site. Sterling Connect:Enterprise permits two methods of initiating data collection: ✦ The preferred method uses a $$ADD record that precedes the data ✦ Another method is to send only data once communications are established. The drawback of the second method is that the batch is identified by the remote name (BSC and SNA), BSC line name, or BSC Auto Connect remote name (if BSC SIGNON is not used), rather than your specific mailbox ID. $$ADD Defaults If a data batch is sent to the host site without a $$ADD record, the following defaults are used: Default Name Description BATCHID BATCH WITHOUT $$ADD ID LINEID for BSC remotes not using the free-form BSC SIGNON MULTXMIT No SCAN No VBQ# Current collection VBQ XMIT No If a data batch is sent to the host site without a $$ADD record during a host-initiated Auto Connect to the remote site, the following defaults are used: 76 Default Name Description BATCHID AC BATCH WITHOUT $$ADD ID The remote name from the Auto Connect list MULTXMIT No SCAN No VBQ# Current collection VBQ XMIT No IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide $$ADD Command Multiple Batches If multiple batches are sent per transmission, precede each batch with a $$ADD record. If multiple batches are sent to the host computer in a single transmission, and the batches are separated by $$ADD records, use caution if the records are blocked by your remote terminal before they are sent to the host site. Sterling Connect:Enterprise cannot detect a $$ADD record unless is the first record in a block of data. Ensure that your remote terminal begins a new block for each $$ADD record. Sterling Connect:Enterprise can also create multiple batches on the VSAM batch files as follows: ✦ At SNA sites, use standard Function Management Headers (FMHs) to separate files sent to the host site. If Sterling Connect:Enterprise receives an End Data Set FMH from the remote site during a data collection, the current batch is marked complete and a new batch is started when the next Begin Data Set FMH is received. ✦ For BSC sites, if Sterling Connect:Enterprise receives a block ending with ETX (X’03’), the current batch is marked complete and a new batch is started with the next data input from the remote site. A new $$ADD record at the beginning of a BSC block causes batch separation as if an ETX had terminated the previous block. Syntax The syntax for the $$ADD command at SNA sites is: $$ADD BATCHID=‘xxx...xxx’ EO=N|Y ID=xxxxxxxx MULTXMIT=NO|YES SCAN=NO|YES TO=N|Y VBQ#=nn XMIT=NO|YES The syntax for the $$ADD command at BSC sites is: $$ADD BATCHID=‘xxx...xxx’ EO=N|Y ID=xxxxxxxx MULTXMIT=NO|YES TO=N|Y VBQ#=nn XMIT=NO|YES [$$END] Description Use any number of blanks to separate operands. Do not use commas to separate operands. $$ADD must begin in the first record position. Note: The parameter setting, SCAN=YES, is ignored on SNA remote sites that have SC=YES defined in the *REMOTES record in the Options Definition File. See the IBM Sterling Connect:Enterprise for z/OS Administration Guide for more information on the SC parameter. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 77 Chapter 4 Remote User Commands $$DELETE Command Any batch on the VSAM batch files can be flagged as deleted by a remote site. To delete a batch, you must know the batch identifiers. Run a directory list to confirm you know the correct batch identification data before deletion. After the host receives the input requests, Sterling Connect:Enterprise processes the delete requests and then turns the line around and sends a message to the remote site concerning the outcome of the $$DELETE request. Ensure that your terminal is ready to first send the $$DELETE request to the host site, then receive the output from the host in the same transmission session. Syntax To flag a batch as deleted from an SNA site, send the host a $$DELETE record in the following format: $$DELETE BATCHID=#nnnnnnn ID=xxxxxxxx To flag a batch as deleted from a BSC site, send the host a $$DELETE record in the following format: $$DELETE BATCHID=#nnnnnnn BCHSEP=OPT1|OPT2 ID=xxxxxxxx Description Use any number of blanks to separate operands. $$DELETE must begin in the first record position. Abbreviate this command as $$DEL. $$DIRECTORY Command Remote sites can send inquiries about the contents of the VSAM batch files to the host by submitting a directory request and their mailbox ID. The directory listing is received in mailbox ID order. Sterling Connect:Enterprise searches the VSAM batch files for all batches that match the submitted mailbox ID. A listing of the batch control information for each batch is sent back to the remote site. It is only possible to obtain a listing of all batches for all mailbox IDs if two conditions exist: 1) a password was defined when Sterling Connect:Enterprise was installed, and 2) the password was appropriately submitted in the $$DIRECTORY command from the remote site. Syntax To request a directory listing from an SNA site, send the host a record in the following format: 78 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide $$DIRECTORY Command $$DIRECTORY ID=xxxxxxxx FORMAT=BID24|BID64 MEDIA=CN|PR|PU|EX|BX PASSWORD=xxxxxxxx To request a directory listing from a BSC site, send the host a record in the following format: $$DIRECTORY BCHSEP=OPT1|OPT2 BLOCK=xx ID=xxxxxxxx FORMAT=BID24|BID64 PASSWORD=xxxxxxxx RECSEP=1E|1F Description Use any number of blanks to separate operands. $$DIRECTORY must begin in the first record position. Abbreviate this command as $$DIR. After the host receives your $$DIRECTORY request, Sterling Connect:Enterprise turns the line around and sends the requested data to the remote site. Ensure that your remote site is ready to send the $$DIRECTORY request to the host site, and receive the output from the host in the same transmission session. Output One record is returned to the remote site for each batch in the VSAM batch files that matches the requested mailbox ID. The directory listings use the following format: xxxxxxxx #nnnnnnn CT=nnnnnnnnn BID=x...x HHMM-YYDDD ICADNURTEMXBSZ VBQnn|OFFLINE The contents of the fields are: Field Description xxxxxxxxx The 8-byte mailbox ID with which the batch is associated #nnnnnnn The 7-digit batch number assigned by Sterling Connect:Enterprise CT=nnnnnnnnn The record/block count in the batch. Depending on the installation parameters, this value is either the total number of records in the batch or the total number of blocks in the batch. Contact your Sterling Connect:Enterprise administrator to determine which value is being used. If the count = 0, then either the batch data collection is in progress or is interrupted before completion. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 79 Chapter 4 Remote User Commands Field Description BATCHID=xx....xx The 64-byte user batch ID assigned to the batch when added to the VSAM batch files. If the batch is created due to an online data collection without a $$ADD record, this field contains: BID=BATCH WITHOUT $$ADD (For Remote Connects) BID=AC BATCH WITHOUT $$ADD (For Auto Connects) If the batch is created in an online data collection with a $$ADD record, but no BATCHID is specified, this field contains BID=NONE. HHMM The time the batch is created YYDDD The Julian date the batch is created I|C|A|D|N|U|R|T|E| M|X|B|S|Z 80 One or more of the letters ICADNURTEMXBSZ occurs in the directory listing. These letters indicate the batch status. I The batch is incomplete; collection is in progress or the transmission is interrupted C The batch is collected from a remote site while Sterling Connect:Enterprise is online. A The batch is added by the offline utilities D The batch is flagged as deleted from the VSAM batch files N The batch is nontransmittable (locked for transmissions). When displayed, this status replaces the D status. This status is set immediately after the batch is successfully collected when the EO=Y option of the $$ADD command is specified. It is also set after a successful transmission of the batch added with the TO=Y option U The batch is unextractable (locked for extractions). When displayed, this status replaces the D or N status. This status is set immediately after the batch is added, when the TO=Y option adds the batch. It is also set after the batch’s successful extraction when the EO=Y option added the batch. R The batch is requestable through a $$REQUEST from a remote site. T The batch is transmitted to a remote site. It is not transmitted on a transmit all for the mailbox ID, but can be transmitted again by specific batch number. E The batch is extracted by host site personnel M The batch is available for multiple transmission and any remote site can request it by its ID. X The batch contains transparent data. B The batch originated at an online BSC remote site S The batch originated at an online SNA remote site. Z EBCDIC data added through the APPC User API IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide SNA Logon System Function Field Description VBQnn|OFFLINE The name of the VSAM batch queue where the data resides. If the batch resides on a VSAM batch queue, which is not currently allocated to Sterling Connect:Enterprise, OFFLINE is displayed instead of the VBQ name. SNA Logon System Function Logon is a system function, rather than a Sterling Connect:Enterprise command. Your remote terminal must log on through VTAM to gain access to Sterling Connect:Enterprise at the host site. The logon function may be totally automated by your remote site, or you may have to type a logon or other command on your terminal’s keyboard. The procedures you must use are determined by host site personnel, not by Sterling Connect:Enterprise. Therefore, this section cannot tell you exactly how to type a logon, or if a logon is automatic for your terminal. It can give you a general idea of the information Sterling Connect:Enterprise requires, but the exact format of the logon may vary. The following is a sample common logon. This example may not necessarily work for your particular installation, and the names in parentheses probably differ for your installation. LOGON APPLID(MAILBOX) LOGMODE(RJE3770) DATA(RMT001) If something is wrong with your logon, you receive the message SESSION NOT BOUND. This means that your logon attempt is rejected, either by the system or by Sterling Connect:Enterprise. Correct the logon format and retype the logon. For MLU support, you must log on for each session you activate. The sessions can use the same format for all the logons, or you may be instructed to use a different remote name for each logon. This decision is made by your host site personnel. MLU supports a maximum of six sessions. Syntax Use the following format to log on from an SNA site. This format may not necessarily work for your particular installation. LOGON APPLID(xxxxxxxx) DATA(xxxxxxxx,,yyyyyyyy,zzzzzzzz) LOGMODE(xxxxxxxxx) Description Sterling Connect:Enterprise gains control when you type a logon. Three key logon items are required. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 81 Chapter 4 Remote User Commands Note: The keywords APPLID, LOGMODE, and DATA are standards for typing a logon, but they are determined by host site personnel. Different keywords may be used, or the information can be typed as positional parameters instead. SNA LOGOFF and $$LOGOFF System Functions Type LOGOFF as a system function or as a Sterling Connect:Enterprise $$ command. In either case, the purpose of the logoff is to end the session with the host site. When the logoff function is processed from a dial-up line, the telephone connection is also dropped. Type the LOGOFF system function as a command on your terminal’s keyboard or press a specified function key. The exact procedure depends upon your terminal type and on the implementation by host site personnel. The $$LOGOFF Sterling Connect:Enterprise function is essentially a data string that Sterling Connect:Enterprise interprets as a request to end the session. For security, correctly type your remote name and the APPLID defined to Sterling Connect:Enterprise. Syntax The Sterling Connect:Enterprise logoff function is initiated by sending the host a record with the following format: $$LOGOFF APPLID=xxxxxxxx RMT=xxxxxxxx Description Use any number of blanks to separate operands. $$LOGOFF must begin in the first record position. $$REQUEST Command Data transmission to your remote site is initiated by sending a $$REQUEST. A request for a transmission can identify a single batch on the VSAM batch files or can request transmission of all batches associated with a mailbox ID. When requesting all batches for a mailbox ID, remember that only batches not already flagged transmitted are sent. A transmission request for a single batch by its batch number can access a batch flagged as already transmitted. If multiple batches are transmitted to a remote site in response to a $$REQUEST for an ID (without a BATCHID), Sterling Connect:Enterprise separates the batches using standard SNA FMHs, unless BCHSEP=OPT3 is used, which concatenates the separate batches into one. 82 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide $$REQUEST Command Syntax At SNA sites, the $$REQUEST record uses the following syntax: $$REQUEST BATCHID=‘xx..xx’|“yyy...yyy”|#nnnnnnn BCHSEP=OPT3 ID=xxxxxxxx MEDIA=xx ONEBATCH=NO|YES TRUNC=NO|YES WAIT=hh:mm:ss,C At BSC sites, the $$REQUEST record uses the following syntax: $$REQUEST BATCHID=‘xx..xx’|“yyy...yyy”|#nnnnnnn BCHSEP=NO|OPT1|OPT2|OPT3 BLOCK=xx CMP=NO|YES ID=xxxxxxxx ONEBATCH=NO|YES RECSEP=xx TRUNC=NO|YES Abbreviate this command as $$REQ. Description Use any number of blanks to separate operands. $$REQUEST must begin in the first record position. Parameter Interrelationships The following is a list of parameter interrelationships: ✦ If TRUNC=Y and CMP=Y are both selected, the data is first truncated and then compressed. ✦ Do not attempt to use BSC transparency in conjunction with blocked data, with TRUNC=Y, or with CMP=Y. ✦ If a batch is requested using BLOCK for blocked data, and if the requested batch is already blocked on the VSAM batch files, double blocking can occur. This is appropriately handled by Sterling Connect:Enterprise, but the remote terminal must be able to deblock such records. $$REQUEST Sample Outputs Sterling Connect:Enterprise uses certain criteria to determine which batches are sent to your remote site for a $$REQUEST. The batch status indicators (such as those displayed for a $$DIRECTORY) are checked and the following rules are applied: Requesting all batches for an ID: $REQUEST ID=xxxxxxxx The batch must be marked R (requestable). The batch must not be marked T (already transmitted), D (deleted), I (incomplete), or N (nontransmittable). Requesting all batches by ID and batch ID: $$REQUEST ID=xxxxxxxx BATCHID=‘xxx...xxx’ IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 83 Chapter 4 Remote User Commands The rules are the same as for requesting all batches for an ID. Requesting a single batch by ID and batch number: $$REQUEST ID=xxxxxxxx BATCHID=#nnnnnnn The batch must be marked R (requestable). The batch must not be marked D (deleted) or N (nontransmittable). If you are unable to request a batch that is on the VSAM batch files, try a $$DIRECTORY and examine the batch status indicators to determine the reason. 84 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Chapter 5 Error Messages Usually the data collection and data transmission processing proceeds with no problems. However, some error messages may occasionally transmit to the remote site. Sometimes when the remote site is expecting to receive a batch data transmission, it may instead receive a message that the requested batch does not exist. Use caution in processing received data to ensure you are not processing an error message from Sterling Connect:Enterprise instead of actual batch data. If your SNA remote site is defined as a console device, you may display these messages on the console screen. All of the remote site messages are identified and explained in this chapter. They are also included in the IBM Sterling Connect:Enterprise for z/OS Error Messages and Codes Guide. Remote User Error Messages (*** ERROR ***) The following is a list of all of the remote site messages. An identifier, description, and action for these messages is included. Message Description Action *** ERROR *** An unidentifiable error occurred at the host. Verify that your input data is correct, and retry the data transmission at a later time. *** ERROR *** BATCH DATA BLOCKS EXCEED BUFFER SIZE. You requested a batch with record sizes that are larger than allowed on the telecommunications line. Try another line which may allow larger records. If it still does not work, you cannot access the batch. Sterling Connect:Enterprise cannot send the batch to you using this line. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 85 Chapter 5 Error Messages 86 Message Description Action *** ERROR ***BSC SIGNON SECURITY VIOLATION. Your BSC SIGNON attempt has failed. Contact host site personnel for further information. *** ERROR *** COLLECTION FAILED. ID VALIDATION FAILED FOR ID=XXXXXXXX. The Sterling Connect:Enterprise system at the host site uses the batch security option. The ID for your input data batch is incorrect, and your batch is rejected. Correct the ID used if it is spelled incorrectly, or contact host site personnel to obtain a valid ID. *** ERROR *** COLLECTION FAILED. SECURITY VIOLATION. You attempted to send batches without following security procedures. These procedures are unique for your installation and are activated by a user security exit. Contact host site personnel if you cannot correct the problem. *** ERROR *** COLLECTION FAILED. INVALID DATA COULD NOT BE DEBLOCKED. You attempted to send batches to the host, but Sterling Connect:Enterprise cannot deblock your data to analyze its contents. This is generally due to a data format error or to a very large data block. Attempt to correct your input data and retry the collection. If the problem persists, contact host personnel. *** ERROR *** COLLECTION FAILED. INVALID FMH SENT. Your remote site sent a Function Management Header (FMH) that is not supported by Sterling Connect:Enterprise. Sterling Connect:Enterprise supports only a 6-character FMH Type 1. If you cannot correct the problem, contact host personnel. *** ERROR *** COLLECTION FAILED. HOST SITE FILE PROBLEM. The host site experienced a problem with its files while attempting to process your data collection. This is usually due to a file full condition or to a very large input data block. If you cannot correct the problem, contact host personnel. *** ERROR *** DATA COLLECTION REJECTED. TRY AGAIN LATER. A temporary busy condition is encountered at the host site. Retry the data collection at a later time. *** ERROR *** DATA COLLECTION ABORTED. TRY AGAIN LATER. An error condition at the host or on the line caused a data collection in progress to fail. The partial data batch is ignored and must be retransmitted at a later time. If this message occurs repeatedly, check the data you are sending the host. Verify the data being transmitted if you receive this error. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Remote User Error Messages (*** ERROR ***) Message Description Action *** ERROR *** ID VALIDATION FAILED FOR ID=xxxxxxxx. The Sterling Connect:Enterprise system at the host site uses the batch security option. The ID in your input data is incorrect, and your communications attempt is rejected. Correct the ID used if it is spelled incorrectly or contact host site personnel to obtain a valid ID. *** ERROR *** INVALID PASSWORD FOR FULL DIRECTORY REQUEST. You attempted a $$DIRECTORY request without supplying a mailbox ID, and you did not supply the correct password. Retype the request with the correct password, or only attempt a $$DIRECTORY for a single mailbox ID. *** ERROR *** INVALID DELETE. BATCH NOT FOUND. You attempted a $$DELETE for a batch that does not exist. Correct the $$DELETE to specify the specific batch for deletion and retry the transmission. *** ERROR *** INVALID DELETE. ENTER ID AND BATCHID=#nnnnnnn. You attempted a $$DELETE but typed the batch identifiers incorrectly. Correct the $$DELETE request and retry the transmission. *** ERROR *** NO BATCHES FOR TRANSMISSION. You have requested a data transmission with a $$REQUEST record, but the batch requested either does not exist or is not available for a data transmission to a remote site. Use a $$DIRECTORY input to verify the identification of the batch. Note: Batches flagged T (transmitted) do not transmit again if you are requesting all batches for a mailbox ID. *** NOTE *** NO BATCHES FOR TRANSMISSION. The host site has initiated a data transmission to your site through the Auto Connect feature. At the time of the Auto Connect, no batches are available for transmission to your remote site. This is normally not an error. None. *** ERROR *** SECURITY VIOLATION. You attempted to access batches without following security procedures. These procedures are unique for your installation and are activated by a user security exit. Contact host site personnel if you cannot correct the problem by changing your batch identifiers. *** ERROR ***SELECTED BATCH ON DEALLOCATED FILE. The selected batch is not accessible because it is located on an offline VSAM batch queue. Contact host site personnel to have the VSAM batch queue allocated and retry your request. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 87 Chapter 5 Error Messages 88 Message Description Action *** ERROR *** SNA BATCH CANNOT BE CONVERTED TO BSC. You attempted to request transmission of a batch which originated at an SNA remote site. The batch contains SNA control characters and cannot be converted and sent to your BSC remote site. The batch is accessible only to host site personnel or to SNA remote sites. Verify batch selection. If correct, contact host site personnel. *** ERROR ***SYSTEM I/O LIMIT REACHED TRY AGAIN LATER. Host system activity is too high to satisfy this request. Try your request later. *** ERROR *** TRANSMIT FAILED. INCORRECT $$LOGOFF OPERAND. You typed a $$LOGOFF command, but failed to supply the appropriate RMT or APPLID parameters. The $$LOGOFF is ignored. Supply the appropriate $$LOGOFF format and retype the request. *** ERROR *** TRANSMIT FAILED. ID VALIDATION FAILED FOR ID=XXXXXXXX. The Sterling Connect:Enterprise system is installed at the host site with the batch security option. The ID you used is incorrect, and your request is rejected. Correct the ID used if it is spelled incorrectly, or contact host site personnel to obtain a valid ID. *** ERROR *** TRANSMIT FAILED. NO BATCHES FOR TRANSMISSION. You have requested a data transmission with the $$REQUEST function, but the batch requested either does not exist or is not available for a data transmission to a remote site. Use a $$DIRECTORY to verify the identification of the batch and to determine if it is transmittable. *** NOTE *** TRANSMIT FAILED. NO BATCHES FOR TRANSMISSION DURING Sterling Connect:Enterprise AUTO CONNECT. The host site initiated a connection to your remote site through the Sterling Connect:Enterprise Auto Connect feature. At this time, no batches are ready for transmission to your remote site. This may not be an error. No batches are sent to you, but you may now have the opportunity to send data to the host site. None. *** ERROR *** TRANSMIT FAILED. INVALID PASSWORD FOR FULL DIRECTORY REQUEST. You attempted a $$DIRECTORY request without supplying an ID, and did not supply the appropriate system password. Retype the $$DIRECTORY with the appropriate password, or attempt a $$DIRECTORY for a single mailbox ID only. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Remote User Error Messages (*** ERROR ***) Message Description Action *** ERROR *** TRANSMIT FAILED. SECURITY VIOLATION. You attempted to access host data without following security procedures. These procedures are unique for your installation and are activated by a user security exit. Contact host site personnel if you cannot correct the problem. *** ERROR *** TRANSMIT FAILED. YOUR REMOTE SENT NEGATIVE RESPONSE TO TRANSMIT. Sterling Connect:Enterprise attempted a data transmission to your remote site, but your remote site rejected it by sending a negative response. This can occur for many reasons. For example, your remote site may want to send data to the host at this time and not receive it. Or, Sterling Connect:Enterprise has directed the batch to a certain media that is currently not ready and available for use. Sterling Connect:Enterprise handles the negative response, and you can retry the failed transmission later if appropriate. Ensure the appropriate output media device is assigned and ready for use. If you cannot determine why your remote site is rejecting a transmission with a negative response, contact host site personnel. Sterling Connect:Enterprise records the transaction that failed and the reason for failure. It may be possible to recreate the problem and have host site personnel explain the negative response. *** ERROR *** TRANSMIT FAILED. DATA CANNOT BE FORMATTED FOR YOUR REMOTE. The batch you have requested cannot be sent to your remote site due to a data formatting problem. This can occur when attempting to transmit BSC originated data to an SNA remote site, or vice versa. If you are unable to correct the problem, contact host site personnel. *** ERROR *** TRANSMIT FAILED. RECORDS ARE TOO LARGE FOR YOUR BUFFER SIZE. The batch you have requested cannot be sent to your remote site. One or more of the batch data records exceeds the buffer size for your remote. Contact remote site personnel if the problem persists and you require access to the batch. They may need to assign a larger buffer to your remote site. *** ERROR *** TRANSMIT FAILED. SELECTED BATCH REQUIRES A STERLING CONNECT REMOTE DEFINITION. The batch you have requested requires a Sterling Connect remote definition to transmit correctly. Your current remote definition is not defined as such. Make the appropriate changes to support Sterling Connect remotes and retry the $$REQUEST or refrain from selecting this batch. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 89 Chapter 5 Error Messages 90 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Notices This information was developed for products and services offered in the U.S.A. IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently available in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service. IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to: IBM Director of Licensing IBM Corporation North Castle Drive Armonk, NY 10504-1785 U.S.A. For license inquiries regarding double-byte character set (DBCS) information, contact the IBM Intellectual Property Department in your country or send inquiries, in writing, to: Intellectual Property Licensing Legal and Intellectual Property Law IBM Japan Ltd. 1623-14, Shimotsuruma, Yamato-shi Kanagawa 242-8502 Japan The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law: INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Some states do IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 91 Notices not allow disclaimer of express or implied warranties in certain transactions, therefore, this statement may not apply to you. This information could include technical inaccuracies or typographical errors. Changes are periodically made to the information herein; these changes will be incorporated in new editions of the publication. IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice. Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites. The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk. IBM may use or distribute any of the information you supply in any way it believes appropriate without incurring any obligation to you. Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact: IBM Corporation J46A/G4 555 Bailey Avenue San Jose, CA__95141-1003 U.S.A. Such information may be available, subject to appropriate terms and conditions, including in some cases, payment of a fee. The licensed program described in this document and all licensed material available for it are provided by IBM under terms of the IBM Customer Agreement, IBM International Program License Agreement or any equivalent agreement between us. Any performance data contained herein was determined in a controlled environment. Therefore, the results obtained in other operating environments may vary significantly. Some measurements may have been made on development-level systems and there is no guarantee that these measurements will be the same on generally available systems. Furthermore, some measurements may have been estimated through extrapolation. Actual results may vary. Users of this document should verify the applicable data for their specific environment. Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the suppliers of those products. All statements regarding IBM's future direction or intent are subject to change or withdrawal without notice, and represent goals and objectives only. 92 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Notices This information is for planning purposes only. The information herein is subject to change before the products described become available. This information contains examples of data and reports used in daily business operations. To illustrate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are ficticious and any similarity to the names and addresses used by an actual business enterprise is entirely coincidental. COPYRIGHT LICENSE: This information contains sample application programs in source language, which illustrate programming techniques on various operating platforms. You may copy, modify, and distribute these sample programs in any form without payment to IBM, for the purposes of developing, using, marketing or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, serviceability, or function of these programs. The sample programs are provided "AS IS", without warranty of any kind. IBM shall not be liable for any damages arising out of your use of the sample programs. Each copy or any portion of these sample programs or any derivative work, must include a copyright notice as follows: © IBM 2011. Portions of this code are derived from IBM Corp. Sample Programs. © Copyright IBM Corp. 2011. If you are viewing this information softcopy, the photographs and color illustrations may not appear. Trademarks The following terms are trademarks of the International Business Machines Corporation in the United States, other countries, or both: http://www.ibm.com/legal/copytrade.shtml. Adobe, the Adobe logo, PostScript, and the PostScript logo are either registered trademarks or trademarks of Adobe Systems Incorporated in the United States, and/or other countries. IT Infrastructure Library is a registered trademark of the Central Computer and Telecommunications Agency which is now part of the Office of Government Commerce. Intel, Intel logo, Intel Inside, Intel Inside logo, Intel Centrino, Intel Centrino logo, Celeron, Intel Xeon, Intel SpeedStep, Itanium, and Pentium are trademarks or registered trademarks of Intel Corporation or its subsidiaries in the United States and other countries. Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. ITIL is a registered trademark, and a registered community trademark of the Office of Government Commerce, and is registered in the U.S. Patent and Trademark Office. IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 93 Notices UNIX is a registered trademark of The Open Group in the United States and other countries. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates. Cell Broadband Engine is a trademark of Sony Computer Entertainment, Inc. in the United States, other countries, or both and is used under license therefrom. Linear Tape-Open, LTO, the LTO Logo, Ultrium and the Ultrium Logo are trademarks of HP, IBM Corp. and Quantum in the U.S. and other countries. Connect Control Center®, Connect:Direct®, Connect:Enterprise, Gentran®, Gentran:Basic®, Gentran:Control®, Gentran:Director®, Gentran:Plus®, Gentran:Realtime®, Gentran:Server®, Gentran:Viewpoint®, Sterling Commerce™, Sterling Information Broker®, and Sterling Integrator® are trademarks or registered trademarks of Sterling Commerce, Inc., an IBM Company. Other company, product, and service names may be trademarks or service marks of others. 94 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Index Symbols $$ADD example 66 header record 66 $$ADD command defaults 76 example 52 header record 52 initiating 76 multiple batches 77 operands 77 syntax BSC 77 FTP 49 SNA 77 operands 83 syntax BSC 83 SNA 83 using 83 $TURNLINE$ 70 A ADD utility VSAM status flags 30 auto connect configuration 51, 66 definition 51, 66 B $$DELETE example 66 $$DELETE command definition 73 example 52 operands 78 syntax BSC 78 SNA 78 $$DIRECTORY command definition 73 operands 79 output 79 syntax BSC 79 SNA 79 $$LOGOFF command definition 73 SNA 82 blocked data records 69 BSC $TURNLINE$ 70 blank compression 68 blank truncation 69 blocked data records 69 options 68 record separator override 69 RJE communication 65 SIGNON implementation 68 temporary text delay 70 transparency 69 WAIT Acknowledgement (WACK) 70 C $$REQUEST example 66 CCC, see Clear Control Channel $$REQUEST command definition 73 example 52 command conventions, FTP 16 Clear Control Channel 14 Commands $$ADD IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 95 Index $$DIRECTORY 73 $$LOGOFF 73 $$REQUEST 73 BSC $TURNLINE$ 70 record separator override 69 temporary text delay 70 WAIT Acknowledgement (WACK) 70 defaults 76 initiating 76 multiple batches 77 operands 77 syntax BSC 77 FTP 49 SNA 77 $$DELETE operands 78 syntax BSC 78 SNA 78 $$DIRECTORY operands 79 output 79 syntax BSC 79 SNA 79 $$LOGOFF SNA 82 $$REQUEST operands 83 SNA 82 syntax BSC 83 SNA 83 using 83 logoff 82 remote site 73 standard FTP syntax del 37 dir 38 get 39 mput 42, 43 pwd 44 recv 39 submitting 73 del standard FTP syntax instructions 37 device media procedures 55 dir standard FTP syntax instructions 38 disconnect interval definition 57 E EBCDIC 57 EXTRACT utility VSAM status flags 30 F firewall navigation 13 FMH batch separation 56 insertion 56 procedures 56 terminal control 56 free-form BSC SIGNON 68 configuration 51, 66 console display implementing 55 messages 55 procedures 55 D data compression 55 Data streams 57, 70 Definition $$DELETE 73 96 FTP data structure 10 data type 8 delimiting records with $$ commands 47 processing $$ADD commands 47 scanning for $$ADD commands 47 transfer mode 11 user batch ID syntax and formats 11 FTP Commands 15 standard FTP syntax del 37 dir 38 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Index Multiple Logical Unit (MLU) 54 get 39 mput 42, 43 pwd 44 recv 39 P pwd instructions 44 FTP SITE command parameters 19 R G Record separator override BSC 69 get standard FTP syntax examples 40 format 40 instructions 39 record separator override blocked data records 69 H host initiated communication definition 51 site 51 recv standard FTP syntax examples 40 instructions 39 Remote site commands 73 host initiated communication definition 66 host site 66 Requirements BSC $TURNLINE$ 70 logon 81 RJE communication 65 I RJE SIGNON 66 IRS (inter-record separator) 69 L log on, FTP 14 Logoff command 82 SNA 82 syntax 82 Logon requirements 81 SNA 81 S SNA logoff 82 logon example of 81 syntax 81 procedures 56 terminal options 54 transparency 56 starting and stopping sessions procedures 51, 65 T M media device support 54 Terminal options SNA 54 MLU, see Multiple Logical Unit transparency SNA 56 mput instructions 42, 43 TTD (temporary text delay) 70 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide 97 Index V VSAM batch status flags list of 30 VTAM Log Mode Table 55 W WAIT acknowledgement (WACK) 70 98 IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide
Source Exif Data:
File Type : PDF File Type Extension : pdf MIME Type : application/pdf PDF Version : 1.5 Linearized : No Page Mode : UseOutlines XMP Toolkit : 3.1-702 Copyright : 2000,2005 Producer : Acrobat Distiller 7.0 (Windows) Creator Tool : FrameMaker 7.2 Modify Date : 2011:03:22 08:56:01-05:00 Create Date : 2011:03:22 08:53:10Z Metadata Date : 2011:03:22 08:56:01-05:00 Format : application/pdf Title : IBM Sterling Connect:Enterprise for z/OS Remote User’s Guide Creator : IBM Document ID : uuid:9ae44b55-0473-4f05-a724-7940295b349f Instance ID : uuid:8723f7d7-feba-43fc-933b-ec162db92a67 Page Count : 98 Author : IBM Warning : [Minor] Ignored duplicate Info dictionaryEXIF Metadata provided by EXIF.tools