******************************************************* * * * FUNCTION: Send a file to the testcase server * * * * PUTDOC Parameters: * * * *** * 1 required positional parameter: * * * * input data set name * * * * Fully qualified, with or without quotes. * * The high level qualifier is removed to * * generate the base of the name of the * * file created on the testcase server. * * * * Please see "Support for multi-part data * * sets" for information on handling large * * and/or fragmented files. * * * * HELP may be entered in place of this * * parameter to generate this display. * * * * --------------------------------------------------- * * --------------------------------------------------- * * * * Other parameters: * * * * ==> pmr number (or other identifying string) * * * * The pmr number or other identifying * * string may be specified at invocation * * using the PR() parameter. Otherwise * * the CLIST will prompt for it. Anything * * specified at invocation is converted to * * lowercase. * * * * ex: PR(ppppp.bbb.ccc) * *** * * * The passed pmr number can be any length but * * is generally 13 Chars in the above format: * * * * ppppp is the 5-char PMR number, eg: 34143 * * bbb is the 3-char branch, eg: 055 * * ccc is the 3-char country code, eg: 724 * * * * This is used to name the target sub * * directory on the testcase server or to * * insert in the filename on testcase. If the * * host is testcase, a pmr number is required. * * * * Established nicknames may include a * * sub directory vs insert designation - if * * not, the CLIST will prompt for it. * * * * --------------------------------------------------- * * --------------------------------------------------- * * * * ==> destination * * * * The destination is the target path on * * the testcase server or another fully * * specified host/pathname. It may be * * specified at invocation using one of the * * defined nicknames or the CLIST will * * prompt for it. * * * * ex: TO(cics) (on command line) * * * *** * TO() accepts only a nickname. The prompt * * allows the user to select from a list or * * enter an alternative destination. * * * * If no destination is specified either at * * invocation or at the prompt, no files will * * be sent. This is useful if you wish only * * to create the intermediate MVS files for * * TERSE and XMIT. * * * * An alternative fully-qualified destination * * host/pathname may be entered. If the * * destination begins with '/', it is treated * * as a path on the testcase server. Paths * * on testcase are displayed that way. * * * * If the target path requires a slash (as in * * an hfs directory on an MVS host), enter * * the slash after the 'host/' : * * * * ex: my.host.name//u/userxx * * * * or enter only the host and wait for the * * CLIST to prompt for the target directory. * * If you designate (via prompt) the remote * * host as MVS, you may press enter at the * * prompt to accept 'userid' as the directory. * * * * * * # Nickname Host/Path * * = ======== ========= * *** * 1 TCPIP ftp.emea.ibm.com/toibm/mvs * * 2 MVS /toibm/mvs * * 3 VTAM ftp.emea.ibm.com/toibm/mvs * * 4 CICS ftp.emea.ibm.com/toibm/mvs * * 5 DB2 /toibm/im * * 6 NETVIEW ftp.emea.ibm.com/toibm/mvs * * 7 S390WEBS ftp.emea.ibm.com/toibm/mvs * * 8 EMEA ftp.emea.ibm.com/toibm/mvs * * 11 S/390 /toibm/mvs * * * * --------------------------------------------------- * * --------------------------------------------------- * * * * ==> userid and password * * * * Userid and password may be specified in * * the following ways: * * * * invocation -- the US() and PW() keywords * * may be used at invocation * * if the destination is not * * testcase (the values are * * always in uppercase). * * * * predefined -- userid and password may * * be coded for each host * * in the CUSTOM section or in * * a PUTDOC profile data set * * * * prompt -- the CLIST will prompt for * * userid and password if * *** * not set at invocation or * * predefined. * * * * A userid and password are required for * * access to all remote systems, including * * the testcase server. In the case of the * * testcase server, the userid is 'anonymous' * * and the password is an email address. * * * * To force an override of a predefined * * userid/password connected to a non-testcase * * destination nickname, at least US(userid) * * must be specified on the command line. * * * * The userid specified must have write access * * to the target directory. * * * * --------------------------------------------------- * * --------------------------------------------------- * * * * ==> type of transfer * * * * The CLIST will attempt to determine the * * type of file being transferred and may * * recommend a type to use. The user is * * asked to confirm the choice. * * * * * * Binary file - see TRS and XMT for TRSMAIN * * tersed and TSO XMIT files * * * *** * > Use for binary data that cannot * * be translated to ASCII and that * * does not need to be terse or XMIT * * * * * * Text file - displayable data * * * * --------------------------------------------------- * * --------------------------------------------------- * * * * Terse file - file is tersed or needs to be * * tersed - the CLIST will determine * * which and verify before transmitting * * * * > Use for all large files * * > Use for files with variable records * * > If the tersed file is too large * * to transmit, it will be split into * * parts before transmission. * * > Tersed files may be encrypted * * * * * * TSO XMIT - file is a TSO XMIT output file * * or needs conversion to one - PUTDOC * * will verify which before transfer * * * * > Use for files with variable records * * > TSO XMIT is only the file format, * * it is not the mode of transmission. * * All files are transmitted using FTP.* * * *** * --------------------------------------------------- * * --------------------------------------------------- * * * * Encrypting the output file: * * * * Data set encryption, using the C/C++ encrypt() * * facility, is available for all sequential files,* * including individual PDS members. The file * * must be tersed or selected to be tersed using * * TRSMAIN before encryption can be done. * * * * If PUTDOC is configured to perform encryption, * * any data set that is already tersed, or is * * selected to be tersed, or is a tersed fragment, * * is eligible to be encrypted. The tool will * * ask whether the file should be encrypted. * * * * You will be prompted for 0 to 8 positions of * * the encryption key. Some or all of your input * * (if any) is folded into the key fields with * * the generated fields. If you enter 8 valid * * characters, that key will be used. Any EBCDIC * * character is accepted except for single or * * double quotes, forward or backward slashes, * * and ampersand (' " / \ &). * * * * The final key used to encrypt the file will * * print in the PUTDOC log. It is placed there * * for reference because the actual key contents * * cannot be reliably predicted. The key also * * prints in the job output. Ensure that both * *** * the log file and the job output are secured. * * * * Report the key contents to the support team * * who is handling your request so that they are * * able to decipher the data. For security * * reasons, please do not place the encryption * * key on the Testcase server. The best method * * of delivering the key contents is by telephone * * or by placing an update in the problem record. * * * * The encryption process creates an additional * * work data set on the local host. Its * * disposition will be the same as that designated * * for all work data sets. * * * * To enable encryption, the programs found on * * the following server must be installed: * * * * ftp://ftp.emea.ibm.com/fromibm/s390/mvs/tools/ * * ftp://ftp.emea.ibm.com/fromibm/mvs/tools/ @C5M * * * * Update the ENCPROGM and, if needed, the * * ENCSTEPL parameters in the CUSTOM section to * * indicate the name and location of the load * * module to use. PUTDOC will not attempt * * encryption until ENCPROGM is set to either * * FTPENCR or FTPENCRD. * * * * The run-time of the batch job when encryption * * is in use is about double that of processing * * the same file without encryption. * *** * * * --------------------------------------------------- * * --------------------------------------------------- * * * * Support for hfs files: * * * * Files in the hfs (Hierarchical File System) * * on an OS/390 platform may be sent with PUTDOC. * * To do so, specify a preexisting but empty MVS * * data set name, or a non-existent MVS data set * * name or PDS member as the source for PUTDOC. * * * * You will be given the option of a BINARY or * * TEXT copy (via OGET) to the MVS file. If the * * file did not exist, OGET will create it and * * determine its attributes. Otherwise, the * * attributes used will be those of the existing * * output MVS data set or PDS. * * * * --------------------------------------------------- * * --------------------------------------------------- * * * * Support for partitioned data sets: * * * * A partitioned data set and optional member(s) * * may be used as input to PUTDOC. Valid forms: * * * * 'my.pds' 'my.pds(member)' * * 'my.pds(*)' 'my.pds(mem*)' * * * * If form 'my.pds' is used (as when PUTDOC is * *** * invoked from the 3.4 panel in ISPF) the CLIST * * will prompt for the specification of member. * * * * If multiple (or all) members of a PDS are * * specified and the destination is Testcase, the * * TERSE option is not available. * * * * If multiple (but not all) members of a PDS * * are specified with a type of XMIT, the matching * * members are first copied to a work PDS and then * * that PDS is converted to TSO TRANSMIT format. * * Note that TSO TRANSMIT is only the file format, * * not the transmission mode. All files are * * transmitted using FTP. * * * * PDSE libraries are supported but members that * * were generated by the binder may not be sent in * * a group. Binder-generated members cannot be * * copied to the intermediate PDS for TSO TRANSMIT * * format and a PDSE cannot be tersed. Binder * * member names must be entered individually. * * * * --------------------------------------------------- * * --------------------------------------------------- * * * * Support for multi-part data sets: * * * * Files that are very large can be tersed and * * then split into parts by PUTDOC. That happens * * automatically based on your SPLTSIZE setting * * in the CUSTOM section. The output files are * *** * placed on the target system with a suffix of * * PnOFm to indicate they are file fragments. * * * * If an untersed INPUT data set is fragmented, * * or tersed fragments must be re-sent, * * PUTDOC will automatically process them with * * some restrictions: * * * * Fragmented untersed INPUT data set: * * * * > All of the parts must be named identically * * except for their last-level qualifier, which * * must be in the form PnOFm (n starts at 1). * * * * > Do NOT terse the individual parts of the * * data set. PUTDOC will take care of that. * * * * > A maximum of nine (9) parts is allowed. All * * files within the range (m) must be found. * * * * > The data set attributes of all the data sets * * must be identical. * * * * > If PUTDOC is issued against any member of a * * group of fragments of an untersed INPUT * * data set, the entire group of data sets * * is processed and sent. * * * * > If the aggregate input file is of sufficient * * size, the tersed copy will be split into * * TERSED FRAGMENTS (see below) before sending. * *** * These fragments will have different names * * from the input fragments. * * * * > If the aggregate input is not large enough to * * force a terse and split, you may choose to * * send it using the TSO TRANSMIT format. The * * file is transmitted using FTP, but is first * * converted to TSO TRANSMIT output format. * * * * * * TERSED FRAGMENTS: * * * * > If the fragments are already tersed, the * * file ** must ** have been tersed before it * * was split. If you have an untersed file * * in fragments, let PUTDOC terse and send it - * * DO NOT terse the fragments first. * * * * > PUTDOC produces tersed fragments when it * * splits a file (see SPLTSIZE). If any of * * the fragments fails to be transmitted, it * * can be re-sent this way. * * * * > A maximum of nine (9) parts is allowed. * * * * > Data sets must contain TRSMAIN output. * * * * > Issue PUTDOC for each TERSED FRAGMENT you * * wish to send. The order of submission is * * not significant - they will be reassembled * * using their PnOFm qualifier. * *** * * * --------------------------------------------------- * * --------------------------------------------------- * * * * International EMEA Repository: * * * * The EMEA repository is an HFS host that is * * used by international customers. It is *not* * * commonly used by domestic customers and should * * not be used unless you have been instructed to * * place documentation there. * * * * o The CLIST will prompt for a userid and * * password or they may be specified on the * * command line using US() and PW(). They * * may also be included in a user's PROFILE * * data set or hardcoded in the nickname for * * EMEA (not recommended). * * * * o Branch Office (General Services #) and * * Country code are hardcoded in the CUSTOM * * section of the CLIST (see EMB and EMC * * parameters). These may be overridden via * * a user's PROFILE data set. * * * * o The EMEA hostname is kept in the EMHOSTN * * parameter in the CUSTOM section. * * * * o The default EMEA directory (toibm/mvs) is * * kept in the PATH parameter of the EMEA * * nickname. * *** * * * o The EMEA nickname (a sample is provided) * * can be moved in the list. This is the * * original sample: * * * * SET NICK8 = &STR(EMEA) * * SET HOST8 = &STR(ftp.emea.ibm.com) * * SET MVSF8 = &STR(N) * * SET USER8 = &STR(anonymous) * * SET PASS8 = &STR() * * SET MORE8 = &STR(NONE) * * SET MOR28 = &STR(NONE) * * SET MOR38 = &STR(NONE) * * SET PATH8 = &STR(toibm/mvs) * * SET PMRD8 = &STR(I) * * * * o Only tersed (or tersed and encrypted) * * data types are accepted. * * * * o The EMEA repository (unlike Testcase) will * * accept a tersed PDS, but the user must * * inform the EMEA support representative * * that the transmitted data set contains * * a PDS. * * * * * * Naming conventions: * * * * o Default PATH is toibm/mvs * * * * o Data sets are named * *** * nnnnn.bbb.ccc.**(.PDS).type(.PnOFm) * * * * Where: * * nnnnn is the 5-digit pmr number * * bbb is the Branch or General Services # * * ccc is the Country code * * ** is your choice * * PDS indicates a tersed PDS * * type is one of the following: * * TRS - tersed file * * CRY - non-DES encrypted * * CRY64 - 64-bit DES encrypted * * PnOFm is optional and is used for * * tersed fragments * * * * * * o The CLIST will prompt for a data set name * * string. Normally 20 positions are * * available but tersed fragments and a * * tersed PDS will reduce the available space.* * Examples: * * * * ONTOP.GSbbb.Pnnnnn.Cccc.**.TRS * * ONTOP.GSbbb.Pnnnnn.Cccc.**.CRY.P1OF5 * * ONTOP.GSbbb.Pnnnnn.Cccc.**.PDS.TRS * * * * o Also, a single member from a PDS can be * * tersed and sent. In that case, then * * member name will be included in the output * * file name thus: * * * *** * ONTOP.GSbbb.Pnnnnn.Cccc.**.member.TRS * * * * The delimiters on either side of the * * string (** above) are added automatically, * * are not included in the number of * * available bytes, and should *not* be * * duplicated in input from the user. * * Delimiters between supplied qualifiers are * * allowed (and required). * * * * --------------------------------------------------- * * --------------------------------------------------- * * * * Disposition of source and work data sets: * * * * The MIGORIG and MIGWORK values in the CUSTOM * * section control the final disposition of the * * original file and any work data sets. * * * * The CLIST will inform you of these settings * * before the job is submitted, and you may * * elect to change as part of the job submission * * process. * * * * MIGORIG is currently set to * * >> No Change << * MIGWORK is currently set to * * >> Delete << * * * --------------------------------------------------- * * --------------------------------------------------- * *** * * * Profile data set: * * * * If users wish to create a profile data set with * * customized settings for their invocations of * * PUTDOC, they may. The syntax rules governing * * the profile data set, the data set name format, * * and the variables that can be changed are * * described in the CUSTOM section of the CLIST. * * Please see your system administrator for more * * information about setting up a profile data set.* * * * --------------------------------------------------- * * --------------------------------------------------- * * * * Abnormal termination support: * * * * In case of abnormal termination of the PUTDOC * * job, all the input and work data sets are kept * * on level 1, and the following data sets may * * aid in restart: * * * * 1) 'HLQ.Tnn.Ppmr.typ.PUTDOC.JCL' * * 2) 'HLQ.Tnn.Ppmr.typ.PUTDOC.FTPMKD' * * 3) 'HLQ.Tnn.Ppmr.typ.PUTDOC.FTPBAT' * * * * Where: * * * * 1) - Contains the JCL for the submitted job * * 2) - Contains input to the mkdir FTP step * * 3) - Contains input to the main FTP step * *** * * * Tnn - time qualifier - all work and output * * files use this as second qualifier * * (except for a target PDS on the * * remote host) * * pmr - pmr number (if any) * * typ - TXT, BIN, TRS, XMT, ECR, ECD * * * * Note that all output data sets are cataloged * * and kept upon abnormal termination. You may * * need to delete some data sets before restart. * * * *******************************************************