366 lines
18 KiB
HTML
366 lines
18 KiB
HTML
|
|
<!doctype html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head><META http-equiv="Content-Type" content="text/html; charset=utf-8">
|
|
<title>Copy To Stream File (CPYTOSTMF)</title>
|
|
<link rel="stylesheet" type="text/css" href="../rzahg/ic.css">
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script language="Javascript" src="../rzahg/synch.js" type="text/javascript"></script>
|
|
<a name="CPYTOSTMF.Top_Of_Page"></a>
|
|
<h2>Copy To Stream File (CPYTOSTMF)</h2>
|
|
<table width="100%">
|
|
<tr>
|
|
<td valign="top" align="left"><b>Where allowed to run: </b>All environments (*ALL)<br>
|
|
<b>Threadsafe: </b>No
|
|
</td>
|
|
<td valign="top" align="right">
|
|
<a href="#CPYTOSTMF.PARAMETERS.TABLE">Parameters</a><br>
|
|
<a href="#CPYTOSTMF.COMMAND.EXAMPLES">Examples</a><br>
|
|
<a href="#CPYTOSTMF.ERROR.MESSAGES">Error messages</a></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<div> <a name="CPYTOSTMF"></a>
|
|
<p>The Copy To Stream File (CPYTOSTMF) command copies either a database file member or a save file to a stream file. Optional conversion of the data and reformatting is performed when copying a database file member. This command cannot be used to copy to or from a database file member on a remote system. Any overrides in effect for the database file member or the save file are not used by this command.
|
|
</p>
|
|
<p>This command can operate on regular files and on the /dev/null character special file. A regular file is a file that supports the integrated file system input/output (I/O) operations open, read, and write.
|
|
</p>
|
|
<p>For more information about integrated file system commands, see the Integrated file system information in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.
|
|
</p>
|
|
<p><b>Restrictions:</b>
|
|
</p>
|
|
<ol>
|
|
<li>The database-member-path-name must be of the form <b>name.object-type</b>. For example, <b>/QSYS.LIB/LIBA.LIB/FILEA.FILE/MBRA.MBR</b> is the form required by the QSYS.LIB file system.
|
|
</li>
|
|
<li>The save-file-path-name must be of the form <b>name.object-type</b>. For example, <b>/QSYS.LIB/LIBA.LIB/SAVEFILEA.FILE</b> is the form required by the QSYS.LIB file system.
|
|
</li>
|
|
<li>The user must have the following authorities:
|
|
<ul>
|
|
<li>Execute (*X) authority to directories in the path name prefix of the database file, save file, stream file or conversion table.
|
|
</li>
|
|
<li>Read, execute (*RX) authority to the database file or save file.
|
|
</li>
|
|
<li>Write (*W) authority to the stream file if the stream file already exists.
|
|
</li>
|
|
<li>Write, execute (*WX) authority to the stream file's parent directory if the stream file does not already exist.
|
|
</li>
|
|
<li>If a conversion table was specified, object operational (*OBJOPR) to the conversion table.
|
|
</li>
|
|
</ul>
|
|
</li>
|
|
</ol>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#CPYTOSTMF.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
<hr size="2" width="100%">
|
|
|
|
<div>
|
|
<h3><a name="CPYTOSTMF.PARAMETERS.TABLE">Parameters</a></h3>
|
|
<table border="1" cellpadding="4" cellspacing="0">
|
|
<!-- col1="10" col2="15" col3="30" col4="10" -->
|
|
<tr>
|
|
<th bgcolor="aqua" valign="bottom" align="left">Keyword</th>
|
|
<th bgcolor="aqua" valign="bottom" align="left">Description</th>
|
|
<th bgcolor="aqua" valign="bottom" align="left">Choices</th>
|
|
<th bgcolor="aqua" valign="bottom" align="left">Notes</th>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href="#CPYTOSTMF.FROMMBR"><b>FROMMBR</b></a></td>
|
|
<td valign="top">From file member or save file</td>
|
|
<td valign="top"><i>Path name</i></td>
|
|
<td valign="top">Required, Positional 1</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href="#CPYTOSTMF.TOSTMF"><b>TOSTMF</b></a></td>
|
|
<td valign="top">To stream file</td>
|
|
<td valign="top"><i>Path name</i></td>
|
|
<td valign="top">Required, Positional 2</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href="#CPYTOSTMF.STMFOPT"><b>STMFOPT</b></a></td>
|
|
<td valign="top">Stream file option</td>
|
|
<td valign="top"><b><u>*NONE</u></b>, *ADD, *REPLACE</td>
|
|
<td valign="top">Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href="#CPYTOSTMF.CVTDTA"><b>CVTDTA</b></a></td>
|
|
<td valign="top">Data conversion options</td>
|
|
<td valign="top"><b><u>*AUTO</u></b>, *TBL, *NONE</td>
|
|
<td valign="top">Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href="#CPYTOSTMF.DBFCCSID"><b>DBFCCSID</b></a></td>
|
|
<td valign="top">Database file CCSID</td>
|
|
<td valign="top">1-65533, <b><u>*FILE</u></b></td>
|
|
<td valign="top">Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href="#CPYTOSTMF.STMFCODPAG"><b>STMFCODPAG</b></a></td>
|
|
<td valign="top">Stream file code page</td>
|
|
<td valign="top">1-32767, <b><u>*STMF</u></b>, *PCASCII, *STDASCII</td>
|
|
<td valign="top">Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href="#CPYTOSTMF.TBL"><b>TBL</b></a></td>
|
|
<td valign="top">Conversion table</td>
|
|
<td valign="top"><i>Path name</i></td>
|
|
<td valign="top">Optional</td>
|
|
</tr>
|
|
<tr>
|
|
<td valign="top"><a href="#CPYTOSTMF.ENDLINFMT"><b>ENDLINFMT</b></a></td>
|
|
<td valign="top">End of line characters</td>
|
|
<td valign="top"><b><u>*CRLF</u></b>, *LF, *CR, *LFCR, *FIXED</td>
|
|
<td valign="top">Optional</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#CPYTOSTMF.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
</div>
|
|
<div> <a name="CPYTOSTMF.FROMMBR"></a>
|
|
<h3>From file member or save file (FROMMBR)</h3>
|
|
<p>Specifies the path name of the database file member or save file from which data is copied. When copying from a member, the file may be a source physical file or a program-described physical file. Source physical files with multiple data fields are not supported.
|
|
</p>
|
|
<p>If the database file is a source physical file, the sequence number and date stamp are removed when the records are written to the stream file.
|
|
</p>
|
|
<p>For more information on specifying path names, refer to "Object naming rules" in the CL concepts and reference topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.
|
|
</p>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#CPYTOSTMF.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
<div> <a name="CPYTOSTMF.TOSTMF"></a>
|
|
<h3>To stream file (TOSTMF)</h3>
|
|
<p>Specifies the path name of the stream file to which data is copied. All directories in the path name must exist. New directories are not created. If the stream file does not exist, it is created.
|
|
</p>
|
|
<p>This command can operate on files of type *STMF and on the /dev/null character special file.
|
|
</p>
|
|
<p>
|
|
<b>Note: </b>The QSYS.LIB and independent ASP QSYS.LIB file systems do not allow attributes to be set, so if the path name specified on the TOSTMF parameter is a QSYS member, diagnostic messages will appear in the joblog. The diagnostic messages will not prevent the copy operation from completing successfully and can be ignored.
|
|
</p>
|
|
<p>For more information on specifying path names, refer to "Object naming rules" in the CL concepts and reference topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.
|
|
</p>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#CPYTOSTMF.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
<div> <a name="CPYTOSTMF.STMFOPT"></a>
|
|
<h3>Stream file option (STMFOPT)</h3>
|
|
<p>Specifies whether the copy operation replaces, adds, or fails to copy the records in a stream file if a stream file with the specified name already exists. If the stream file does not exist, it is created.
|
|
</p>
|
|
<dl>
|
|
<dt><b><u>*NONE</u></b></dt>
|
|
<dd>No records are copied and the operation will fail.
|
|
</dd>
|
|
<dt><b>*ADD</b></dt>
|
|
<dd>The records are added to the end of the existing stream file records.
|
|
<p>This value is not allowed when copying a save file.
|
|
</p>
|
|
</dd>
|
|
<dt><b>*REPLACE</b></dt>
|
|
<dd>The records replace the existing stream file records.
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#CPYTOSTMF.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
<div> <a name="CPYTOSTMF.CVTDTA"></a>
|
|
<h3>Data conversion options (CVTDTA)</h3>
|
|
<p>Specifies the process for converting the data from the database file member to the stream file.
|
|
</p>
|
|
<p>This parameter is ignored when copying a save file.
|
|
</p>
|
|
<dl>
|
|
<dt><b><u>*AUTO</u></b></dt>
|
|
<dd>The data is converted during the copy operation using the coded character set identifier (CCSID) equivalent of the stream file data code page and the database file CCSID. Single-byte, double-byte and mixed character sets are supported. The stream file data code page must be specified on the <b>Stream file code page (STMFCODPAG)</b> parameter, and the database file CCSID must be specified on the <b>Database file CCSID (DBFCCSID)</b> parameter.
|
|
</dd>
|
|
<dt><b>*TBL</b></dt>
|
|
<dd>The data is converted using a conversion table. Only single-byte character sets are supported. The conversion table must be specified by the <b>Conversion table (TBL)</b> parameter. If a conversion table is not available, the operation will fail.
|
|
</dd>
|
|
<dt><b>*NONE</b></dt>
|
|
<dd>Only the removal of the sequence numbers and date stamp from source physical files and the optional insertion of specified line-formatting characters into the stream file are performed. Database file CCSID to stream file code page conversion of other characters is not performed.
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#CPYTOSTMF.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
<div> <a name="CPYTOSTMF.DBFCCSID"></a>
|
|
<h3>Database file CCSID (DBFCCSID)</h3>
|
|
<p>Specifies the method of obtaining the database file CCSID.
|
|
</p>
|
|
<p>This parameter is ignored when copying a save file.
|
|
</p>
|
|
<dl>
|
|
<dt><b><u>*FILE</u></b></dt>
|
|
<dd>The database file CCSID is used, unless it is 65535. If the database file CCSID is 65535, and the file is not a program-described file, the operation will fail. If the database file CCSID is 65535, and the file is a program-described file, the default job CCSID is used.
|
|
</dd>
|
|
<dt><b><i>1-65533</i></b></dt>
|
|
<dd>Specify the database file coded character set identifier (CCSID).
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#CPYTOSTMF.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
<div> <a name="CPYTOSTMF.STMFCODPAG"></a>
|
|
<h3>Stream file code page (STMFCODPAG)</h3>
|
|
<p>Specifies the method of obtaining the stream file code page and the CCSID equivalent of the code page that is used for data conversion.
|
|
</p>
|
|
<p>This parameter is ignored when copying a save file.
|
|
</p>
|
|
<dl>
|
|
<dt><b><u>*STMF</u></b></dt>
|
|
<dd>If the stream file exists, and data conversion is requested, the CCSID equivalent of the code page associated with the stream file is used to perform the conversion.
|
|
<p>If the stream file does not exist, the code page equivalent of the source database file CCSID is used and associated with the stream file.
|
|
</p>
|
|
<p>If the data base file CCSID is a mixed encoding scheme, only the single-byte code page is written to the stream file.
|
|
</p>
|
|
</dd>
|
|
<dt><b>*STDASCII</b></dt>
|
|
<dd>If the stream file exists, this option is valid only if the code page associated with the stream file is the same as the specified value. Otherwise, the operation will fail.
|
|
<p>If the stream file does not exist, a code page in the IBM PC Data encoding scheme (x2100) is computed. This code page is associated with the target stream file and is used for data conversion if it is requested.
|
|
</p>
|
|
</dd>
|
|
<dt><b>*PCASCII</b></dt>
|
|
<dd>If the stream file exists, this option is valid only if the code page associated with the stream file is the same as the specified value. Otherwise, the operation will fail.
|
|
<p>If the stream file does not exist, a code page in the Microsoft Windows encoding scheme (x4105) is computed. (Microsoft, Windows, Windows NT, and the Windows 95 logo are registered trademarks of Microsoft Corporation). This code page is associated with the target stream file and is used for data conversion if it is requested. This option allows the resulting data to be used by Microsoft Windows applications.
|
|
</p>
|
|
</dd>
|
|
<dt><b><i>1-32767</i></b></dt>
|
|
<dd>Specify the code page used. If the stream file exists, this option is only valid if the code page associated with the stream file is the same as the specified value. Otherwise, the operation will fail. If the stream file does not exist, the specified code page is associated with the stream file when it is created.
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#CPYTOSTMF.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
<div> <a name="CPYTOSTMF.TBL"></a>
|
|
<h3>Conversion table (TBL)</h3>
|
|
<p>Specifies the path name of the conversion table used to convert data from the database file member to the stream file.
|
|
</p>
|
|
<p>For more information on specifying path names, refer to "Object naming rules" in the CL concepts and reference topic in the iSeries Information Center at http://www.ibm.com/eserver/iseries/infocenter.
|
|
</p>
|
|
<p>
|
|
<b>Note: </b>This parameter is required and valid only if CVTDTA(*TBL) is specified. This parameter is ignored when copying a save file.
|
|
</p>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#CPYTOSTMF.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
<div> <a name="CPYTOSTMF.ENDLINFMT"></a>
|
|
<h3>End of line characters (ENDLINFMT)</h3>
|
|
<p>Specifies the end-of-line characters to insert into the stream file during the copying of records.
|
|
</p>
|
|
<p>This parameter is ignored when copying a save file.
|
|
</p>
|
|
<p>If one of the end-of-line character options is selected (ENDLINFMT(*FIXED) is not specified) the database file records are transformed to variable-length stream file text lines as they are copied. Each database file record is trimmed of any trailing blanks. Then, the data is converted to the destination data format (if specified) and the end-of-line character is appended to the end of the text line. The text line is copied to the stream file.
|
|
</p>
|
|
<dl>
|
|
<dt><b><u>*CRLF</u></b></dt>
|
|
<dd>Carriage-return followed by line-feed is appended to the end of each line.
|
|
</dd>
|
|
<dt><b>*LF</b></dt>
|
|
<dd>Line-feed is appended to the end of each line.
|
|
</dd>
|
|
<dt><b>*CR</b></dt>
|
|
<dd>Carriage-return is appended to the end of each line.
|
|
</dd>
|
|
<dt><b>*LFCR</b></dt>
|
|
<dd>Line-feed followed by carriage-return is appended to the end of each line.
|
|
</dd>
|
|
<dt><b>*FIXED</b></dt>
|
|
<dd>The lines in the stream file are written as fixed length records. CR and LF characters are not added at the end of each line, trailing blanks are not removed from the end of each record. The length of the stream file records equals the length of the database file records.
|
|
<p>Only stream files and database files with compatible encoding schemes which do not result in the expansion of data record lengths are valid with this option. If an incompatible combination of encoding schemes is detected, the operation will fail.
|
|
</p>
|
|
<p>The following encoding scheme combinations are supported:
|
|
</p>
|
|
<ul>
|
|
<li>Single-byte to single-byte
|
|
</li>
|
|
<li>Double-byte to double-byte
|
|
</li>
|
|
<li>Mixed ASCII to mixed ASCII
|
|
</li>
|
|
<li>Mixed EBCDIC to mixed EBCDIC
|
|
</li>
|
|
</ul>
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#CPYTOSTMF.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
<hr size="2" width="100%">
|
|
<div><h3><a name="CPYTOSTMF.COMMAND.EXAMPLES">Examples</a> </h3>
|
|
<p><b>Example 1: Copying Data from a Database File Member to a Stream File Using Automatic Conversion</b>
|
|
</p>
|
|
<p>
|
|
<pre>
|
|
CPYTOSTMF FROMMBR('/QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MYMBR.MBR')
|
|
TOSTMF('STMF.TXT')
|
|
</pre>
|
|
</p>
|
|
<p>This command copies the data contained in database file member /QSYS.LIB/MYLIB.LIB/MYFILE.FILE/MYMBR.MBR to a stream file named STMF.TXT in the current working directory. Automatic data conversion uses the database file CCSID and the code page equivalent of the database file CCSID. The database file member records are stripped of trailing blanks, and CR and LF characters are inserted at the end of each record since ENDLINFMT(*CRLF) is the default value. If the stream file STMF.TXT already exists in the current working directory, the copy operation is not performed since STMFOPT(*NONE) is the default value.
|
|
</p>
|
|
<p><b>Example 2: Copying Data from a Database File Member to a Stream File Using a Conversion Table</b>
|
|
</p>
|
|
<p>
|
|
<pre>
|
|
CPYTOSTMF FROMMBR('/QSYS.LIB/FINANCE.LIB/STAFF.FILE/MNGR.MBR')
|
|
TOSTMF('/MYDIR/FINANCE.MNG') CVTDTA(*TBL)
|
|
DBFCCSID(37) STMFCODPAG(437)
|
|
TBL('/QSYS.LIB/QUSRSYS.LIB/TBL1.TBL')
|
|
ENDLINFMT(*CRLF)
|
|
</pre>
|
|
</p>
|
|
<p>This command copies the data contained in database file member /QSYS.LIB/FINANCE.LIB/STAFF.FILE/MNGR.MBR to a stream file named FINANCE.MNG in the user directory /MYDIR. The data is converted using the conversion table TBL1.TBL contained in the directory /QSYS.LIB/QUSRSYS.LIB. The records in the database file member are trimmed of any trailing blanks, appended with CR and LF characters, and written to the stream file. The blank characters in the database file member are recognized from CCSID 37 specified on the DBFCCSID parameter. The inserted line-formatting characters: CR and LF, correspond to those of code page 437 specified on the STMFCODPAG parameter. If the stream file exists, it must have a code page of 437.
|
|
</p>
|
|
<p><b>Example 3: Copying Data from a Database File Member to a Stream File Without Data Conversion</b>
|
|
</p>
|
|
<p>
|
|
<pre>
|
|
CPYTOSTMF FROMMBR('/QSYS.LIB/FINANCE.LIB/STAFF.FILE/MNGR.MBR')
|
|
TOSTMF('/MYDIR/FINANCE.MNG') CVTDTA(*NONE)
|
|
ENDLINFMT(*FIXED)
|
|
</pre>
|
|
</p>
|
|
<p>This command copies the data contained in database file member /QSYS.LIB/FINANCE.LIB/STAFF.FILE/MNGR.MBR to the stream file FINANCE.MNG in the user directory MYDIR without data conversion. The stream file data is written as fixed-length records of the same length as the database file records. No line-formatting characters are inserted since ENDLINFMT(*FIXED) is specified. If the encoding scheme of the stream file and the database file differ, the copy ends with an error message.
|
|
</p>
|
|
<p><b>Example 4: Copying Data from a Save File to a Stream File</b>
|
|
</p>
|
|
<p>
|
|
<pre>
|
|
CPYTOSTMF FROMMBR('/QSYS.LIB/PACKAGE.LIB/SOFTWARE.FILE')
|
|
TOSTMF('/MYDIR/SOFTWARE')
|
|
</pre>
|
|
</p>
|
|
<p>This command copies the data contained in save file /QSYS.LIB/PACKAGE.LIB/SOFTWARE.FILE to the stream file /MYDIR/SOFTWARE. The stream file data is written as fixed-length records of the same length as the save file records. No line-formatting characters are inserted, nor is any data conversion performed.
|
|
</p>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#CPYTOSTMF.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
<hr size="2" width="100%">
|
|
<div><h3><a name="CPYTOSTMF.ERROR.MESSAGES">Error messages</a> </h3>
|
|
<p><b><u>*ESCAPE Messages</u></b>
|
|
</p>
|
|
<dl>
|
|
<dt><b>CPFA085</b></dt>
|
|
<dd>Home directory not found for user &1.
|
|
</dd>
|
|
<dt><b>CPFA097</b></dt>
|
|
<dd>Object not copied. Object is &1.
|
|
</dd>
|
|
</dl>
|
|
</div>
|
|
<table width="100%">
|
|
<tr><td align="right"><a href="#CPYTOSTMF.Top_Of_Page">Top</a></td></tr>
|
|
</table>
|
|
</body>
|
|
</html>
|