PUTDOC

Country/region [select]

Home

Products

eServer support
iSeries support
pSeries support
xSeries support
zSeries support

Related links
	Developers
	eServer news
	Events
	How to buy

PUTDOC Utility for z/OS and OS/390

PUTDOC is a tool which uses FTP to send documentation files to the Testcase server at IBM. PUTDOC can greatly simplify the transmission of problem related documentation to IBM by automating many of the steps required to submit documentation.

Highlights:

TSO CLIST
Supports sequential and partitioned data sets.
Supports compressed (via TRSMAIN) and TSO transmit formats.
Requires TRSMAIN (see http://techsupport.services.ibm.com/390/trsmain.html).
Optionally encrypts files (requires encryption tool, see http://www.ibm.com/de/support/ecurep/mvs_encryption.html.).
Converts files to requested format before sending.
Supports HFS files.
Logs all activity.
Splits very large tersed files into multiple parts.

License Agreement

Legal Information

International License Agreement for Non-Warranted Programs
Part 1 - General Terms
------------------------------------------------------------------------------------------------------------------
PLEASE READ THIS AGREEMENT CAREFULLY BEFORE USING THE PROGRAM.  IBM WILL LICENSE  THE PROGRAM TO YOU ONLY IF YOU FIRST ACCEPT THE TERMS OF THIS  AGREEMENT.  BY USING THE PROGRAM YOU AGREE TO THESE TERMS.  IF YOU DO NOT AGREE TO THE TERMS OF  THIS AGREEMENT, PROMPTLY RETURN THE UNUSED PROGRAM TO THE PARTY  (EITHER IBM OR ITS RESELLER) FROM WHOM YOU ACQUIRED IT TO RECEIVE A REFUND OF THE AMOUNT YOU PAID.
The Program is owned by International Business Machines Corporation or one of its subsidiaries (IBM)  or an IBM supplier, and is copyrighted and licensed, not sold.
The term "Program" means the original program and all whole or  partial copies of it. A Program consists of machine-readable instructions, its components,  data, audio-visual content (such as images, text, recordings, or pictures), and related licensed materials.
This Agreement includes Part 1 - General Terms and Part  2 - Country-unique Terms and is the complete agreement regarding the use of this Program, and replaces any prior oral or  written communications between you and IBM.  The terms of Part 2 may replace or modify those of Part 1.
1.  License
Use of the Program
IBM grants you a nonexclusive license to use the Program.
    You may 1) use the Program to the extent of authorizations you have acquired and 2) make  and install copies  to  support the level of use authorized, providing you reproduce the copyright notice and any other legends of ownership on each copy, or partial copy, of the Program.
    If you acquire this Program as a program upgrade, your authorization to use the Program from which you upgraded is terminated.
    You will ensure that anyone who uses the Program does so only  in compliance with the terms of this Agreement.
    You may not 1) use, copy, modify, or distribute  the Program except as provided in this Agreement; 2) reverse assemble, reverse  compile, or otherwise translate the Program except as specifically permitted by law without the possibility of contractual waiver; or 3) sublicense, rent, or lease the Program.
    Transfer of Rights and Obligations
    You may transfer all your  license rights and obligations under a Proof of Entitlement for the Program to another party by transferring the Proof of Entitlement and a copy of this Agreement  and all documentation.  The transfer of your license rights and obligations terminates your authorization  to use the Program under the Proof of Entitlement.
2.  Proof of Entitlement
    The Proof of Entitlement for this Program is evidence of your authorization to use this  Program and of your eligibility for future upgrade program prices (if  announced) and potential special or promotional opportunities.
3.  Charges and Taxes
IBM  defines  use for the program for charging purposes and specifies it in the Proof of Entitlement. Charges are based on extent of use authorized. If you wish to increase the  extent of use, notify IBM or its reseller and pay any applicable charges. IBM does not give refunds or credits for charges already due or paid.
    If any authority imposes a duty, tax, levy or  fee, excluding those based on IBM's net income, upon the Program supplied by IBM under this Agreement, then you  agree to pay that amount as IBM specifies or supply exemption documentation.
4.  No Warranty
    SUBJECT TO ANY STATUTORY WARRANTIES WHICH CAN NOT BE  EXCLUDED, IBM MAKES NO WARRANTIES OR CONDITIONS EITHER EXPRESS OR IMPLIED, INCLUDING  WITHOUT LIMITATION, THE WARRANTY OF NON-INFRINGEMENT AND  THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, REGARDING THE PROGRAM OR  TECHNICAL SUPPORT, IF ANY. IBM MAKES NO WARRANTY REGARDING THE CAPABILITY OF THE PROGRAM  TO CORRECTLY PROCESS, PROVIDE AND/OR RECEIVE DATE DATA WITHIN AND BETWEEN THE 20TH AND 21ST CENTURIES.
    The exclusion also applies to any of IBM's subcontractors,  suppliers, or program developers (collectively called "Suppliers").
    Manufacturers, suppliers, or publishers of non-IBM Programs may provide their own warranties.
5.  Limitation of Liability
    NEITHER IBM NOR ITS SUPPLIERS  WILL BE LIABLE FOR ANY DIRECT OR INDIRECT DAMAGES, INCLUDING WITHOUT LIMITATION, LOST PROFITS, LOST SAVINGS, OR  ANY INCIDENTAL, SPECIAL, OR OTHER ECONOMIC CONSEQUENTIAL DAMAGES,  EVEN IF IBM IS INFORMED OF THEIR POSSIBILITY. SOME JURISDICTIONS DO NOT ALLOW  THE EXCLUSION OR LIMITATION OF INCIDENTAL OR CONSEQUENTIAL DAMAGES, SO THE ABOVE EXCLUSION OR LIMITATION MAY NOT APPLY TO YOU.
6.  General
    Nothing in this Agreement affects any statutory rights of consumers that cannot be waived or limited by contract.
    IBM may terminate your license if you fail to comply with the terms of this  Agreement. If IBM does so, you must immediately destroy the Program and all copies you made of it.
    You agree to comply with applicable export laws and regulations.
    Neither you nor IBM will bring a legal action under this Agreement more than two years after the cause of action arose unless otherwise provided by local law without the possibility of contractual waiver  or limitation.
    Neither you nor IBM is responsible for failure to fulfill any obligations due to causes beyond its control.
    IBM does not provide program services or technical support, unless IBM specifies otherwise.
    The laws of the country in which you acquire the Program govern this Agreement,  except 1) in Australia, the laws of the State or Territory in which the transaction is performed govern this Agreement; 2) in Albania,  Armenia,  Belarus, Bosnia/Herzegovina, Bulgaria, Croatia, Czech Republic, Federal Republic of Yugoslavia, Georgia, Hungary, Kazakhstan, Kirghizia,  Former Yugoslav Republic of Macedonia (FYROM), Moldova, Poland, Romania, Russia, Slovak Republic, Slovenia, and Ukraine, the laws of Austria  govern this Agreement; 3) in the United Kingdom, all disputes relating to  this Agreement will be governed by English Law and will be submitted to the exclusive jurisdiction of the English courts; 4) in Canada, the laws in the Province of Ontario govern this Agreement; and 5) in the United  States and Puerto Rico, and People's Republic of China, the laws of the State of New York govern this Agreement.
	      International License Agreement for Non-Warranted Programs
Part 2 - Country-unique Terms
------------------------------------------------------------------------------------------------------------------
AUSTRALIA: No Warranty (Section 4):  The following paragraph is added to this Section:
Although IBM specifies that there are no warranties, you may have certain rights under the Trade Practices Act 1974 or other legislation and are only limited to the extent permitted by the applicable legislation.
Limitation of Liability (Section 5): The following paragraph is added to this Section:
Where  IBM  is in breach of a condition or warranty implied by the Trade Practices Act 1974, IBM's liability is limited to the repair or replacement of the goods, or the supply of equivalent goods. Where that condition or warranty relates to right to  sell, quiet possession or clear title, or the goods are of a kind ordinarily acquired for personal, domestic or household use or consumption, then none of the limitations in this paragraph apply.

GERMANY: No Warranty (Section 4):  The following paragraphs are added to this Section:
The minimum warranty period for Programs is six months.
In case a Program is delivered without Specifications, we will only warrant that the  Program information correctly describes the Program and that the Program can be used according to the  Program information. You have to check the usability according to the Program information within the "money-back guaranty" period.
Limitation of Liability (Section 5): The following paragraph is added to this Section:
The limitations and exclusions specified in the Agreement will not apply to damages caused  by IBM with fraud or gross negligence, and for express warranty.

INDIA: General (Section 6): The following replaces the fourth paragraph of this Section:
If no suit or other legal action is brought, within two years after the cause of action arose,  in respect of any claim that either party  may have against the other, the rights of the concerned party in respect of such claim will be forfeited and the other party will stand released from its obligations in respect of such claim.

IRELAND: No Warranty (Section 4):  The following paragraph is added to this Section:
Except as expressly provided in these terms and conditions, all statutory  conditions, including all warranties implied, but without prejudice to the generality of the foregoing, all warranties implied by the Sale of Goods Act 1893 or the Sale of Goods and Supply of Services Act 1980 are hereby excluded.

ITALY: Limitation of Liability (Section 5): This Section is replaced by the following:
Unless otherwise provided by mandatory law, IBM is not liable for any damages which might arise.

NEW  ZEALAND: No Warranty (Section 4):  The following paragraph is added to this Section:
Although IBM specifies that there  are no warranties, you may have certain rights under the Consumer Guarantees Act 1993 or other legislation which cannot be excluded  or limited. The Consumer Guarantees Act 1993 will not apply in respect of any goods or  services which IBM provides, if you require the goods or services for the purposes of a business as defined in that Act.

Limitation of Liability (Section 5):  The following paragraph is added to this Section:
Where Programs are not acquired for the purposes of a business as defined in the Consumer Guarantees Act 1993, the limitations in this Section are subject to the limitations in that Act.

PEOPLE'S REPUBLIC OF CHINA: Charges (Section 3): The following paragraph is added to the Section:
All banking charges incurred in the  People's Republic of China will be borne by you and those incurred outside the People's Republic of China will be borne by IBM.

UNITED KINGDOM: Limitation  of Liability (Section 5):  The following paragraph is added to this Section at the end of the first paragraph:
The limitation of liability will not apply to any breach of IBM's obligations implied by Section 12 of the Sale of Goods Act 1979 or Section 2 of the Supply of Goods and Services Act 1982.

Accept License

Cancel

Downloading PUTDOC

Prior to downloading you must review and accept the License agreement above.

The binary source file for PUTDOC is available via anonymous ftp to ftp.software.ibm.com in directory s390/mvs/tools/putdoc. Click on one of the options below for detailed instructions to download PUTDOC directly to the z/OS or OS/390 Host, or via the workstation.

Downloading directly to your z/OS or OS/390 Host:
- Click here for instructions on submitting a Batch JOB.
- Click here for instructions using anonymous File Transfer Protocol (FTP) from a TSO command line.
Downloading through the workstation:
- Click here for instructions to download directly from your browser to your workstation.
- Click here for instructions using anonymous File Transfer Protocol (FTP) from your workstation.
Once downloaded to the workstation, the file must be uploaded to the z/OS or OS/390 Host system.

A plain text source file is also available at ftp://ftp.software.ibm.com/s390/mvs/tools/putdoc/putdoc.src

Installing PUTDOC

Once you have used one of the methods above to place a data set containing PUTDOC (attributes are RECFM=FB, LRECL=80) on your z/OS or OS/390 Host system, you must install the PUTDOC CLIST in a library.

Once the PUTDOC CLIST has been downloaded, allocate or identify a data set (usually a partitioned data set or PDS) from which the CLIST will be executed. Ideally, a PDS in the SYSPROC concatenation for users who will be invoking PUTDOC is used.

Using PUTDOC

The PUTDOC CLIST is designed to be run as a line command from a data set list generated from the ISPF 3.4 panel (Data Set List Utility). It can also be run from TSO (it uses no ISPF services). Once installed and customized, it can be invoked against one or more data sets on the list. The command line parameters TO() and PR() can be used to increase efficiency when multiple files are being sent as the '=' parameter can be used to replicate all the settings from the first data set chosen.

It should be noted that the data set name parameter must always be fully qualified, with or without quotes. The purpose of this requirement is to ease difficulties when using explicit CLIST invocation --
exec 'my.clist.lib(putdoc)' 'userid.data.set to(tcpip) pr(12345)'
-- but can be confusing when implicit invocation is used in straight TSO, where
putdoc userid.data.set to(tcpip) pr(12345)
is equivalent to
putdoc 'userid.data.set' to(tcpip) pr(12345).

PUTDOC uses the CLRSCRN utility if it is available, or any other function of your choosing, to enhance readability. Such a routine is not required, however. If you do use CLRSCRN, you should not use extended implicit invocation of the CLIST -- %putdoc -- or you may have problems with the prompts. Each of the prompts within the PUTDOC CLIST will accept QUIT as an option (except as noted).

PUTDOC creates and disposes of all the intermediate data sets it requires based on customization parameters. The user has the option to override the disposition before the job is submitted. The original data set may be migrated or kept on DASD, the work data sets have the additional option of being deleted. For large transfers, it's a good idea to retain the intermediate data sets until all the jobs complete. The intermediate data sets may hold PDS members, tersed output (from TRSMAIN), TSO transmit output, tersed output that has been encrypted, or tersed output that has optionally been encrypted and then split into fragments. These data sets are the files that are transferred to Testcase and they may represent substantial processing prior to the actual transfer.

If the file transfer fails and the previous processing was not complex, it is best to rerun PUTDOC from the beginning. This helps avoid problems with file names, etc. If the file transfer fails and the previous processing was complex, and all steps prior to the FTP step completed successfully, you can restart the job. Look for data sets named similarly to this:

hlq.Tnn.P12345.TRS.PUTDOC.FTPBAT
hlq.Tnn.P12345.TRS.PUTDOC.JCL
hlq.Tnn.P12345.TRS.PUTDOC.LOG

The hlq is variable, as is the Tnn time qualifier. Also, your third qualifier may look different (as in PMR12345). The fourth qualifier represents the type of data -- BIN, ECD, ECR, TRS, TXT, XMT -- and the last two qualifiers are constant. These data sets can be used to restart the transfer to Testcase, with the following considerations:

The file name sent on the second attempt (the file name being placed on Testcase) MUST be different from the previous attempt if any part of the transfer was successful. Testcase will not allow you to overwrite a file. The simplest way to change the name is to change the Tnn qualifier used in the output file name in the .FTPBAT data set. If you wish to have the name logged correctly, you should update the LOG data set prior to restarting the job. See the note below on tersed fragments.
You must remove any steps (such as TRSMAIN or IDCAMS) prior to the FTP step from the JCL data set and run only the FTP step and whatever follows. Be sure that the resulting JCL is executable and contains no unresolved referbacks to DD names or data sets.
Tersed fragments are the data sets created when the size of a tersed file is projected to be larger than the SPLTSIZE value specified in the CUSTOM section of the CLIST. The fragmented files are all transmitted within the same job, so when the FTPBAT file is updated with a new Tnn value, all the file names can be changed at once when all are being re-transmitted. However, if a large amount of data has been successfully transferred, don't transfer it again. Just prune the data sets that have been successfully transferred from the FTPBAT input and make the changes needed for any data sets that were not successfully transferred or transferred only partially. Tersed fragments are identifiable by their .PmOFn last level qualifier.
If you wish, you may send PUTDOC intermediate files using PUTDOC. The result will be duplication of the Tnn qualifier and some other data may be repeated. To eliminate this problem, you may rename the data sets prior to using PUTDOC to send them. In a future release of PUTDOC, this step may be done automatically on the re-transmission.

Inform the support personnel of the names of all the files that were transferred to Testcase. Note: the file names placed on Testcase often do not match the names of the MVS data set or the intermediate data sets. More information is transferred within the file name so that support personnel can readily interpret the data. The final data set names can be found in the PUTDOC LOG data set as long as any changes you made to FTPBAT were also made to the job's interim LOG data set.

Files that have been compressed with TRSMAIN may also be encrypted using the encryption software (see above or http://www.ibm.com/de/support/ecurep/mvs_encryption.html). The CLIST will prompt for the encryption key -- you may enter nothing or up to the full 8 positions of the key. Some or all of your input shorter than 8 positions is inserted randomly into a generated key. If you enter no data for the encryption key, PUTDOC will generate the entire 8 character key. The resulting key will be displayed at the final prompt and logged in the LOG data set. Communicate the encryption key to your support representative as they request. Do not place the encryption key on the Testcase server. Encrypted files have the type ECR (non-DES) or ECD (DES 64-bit encryption) on Testcase.

If you have any questions or problems using PUTDOC, please forward them to tcpdoc@us.ibm.com.

PUTDOC Help text

To read the PUTDOC HELP text, issue the command
  PUTDOC HELP
  or
  EXEC 'my.lib.clist(PUTDOC)' 'HELP'
to display the help text for PUTDOC. This will provide an overview of the functions of the CLIST.

The HELP text is also available at ftp://ftp.software.ibm.com/s390/mvs/tools/putdoc/putdoc.help.txt

Customizing PUTDOC

After reviewing the HELP text, browse the CLIST and look for this label:

CUSTOM:

This is where the customization section begins. Follow the instructions to customize PUTDOC for your installation. Items to be customized include:

Destination Nicknames - some are provided, more can be configured
Parameters used to access the Testcase server from your site
Allocation parameters - work unit, max units, max extent size
Size at which to split very large tersed files
STEPLIB for executing TRSMAIN (if required)
JOB cards
FTPDATA file name
Disposition of input and work data sets

The CLIST variables can be overridden during execution by using a PUTDOC profile data set. Look in the CUSTOM section for instructions.

The CUSTOM text is also available at ftp://ftp.software.ibm.com/s390/mvs/tools/putdoc/putdoc.custom.txt

Related information

TESTCASE Site. U.S. data exchange site.

ECuRep Site EMEA data exchange site.

File Exchange Procedures.

TRSMAIN. Data compression utility.

Encryption Encryption utility.

This page last updated January, 2003.

About IBM

Privacy

Contact