CONVERT[/qualifier[s] infile outfile /[NO]APPEND /BLOCK_SIZE:n /[NO]FIXED_CONTROL /[NO]IDENTIFICATION /INDEXED /KEY[:n] /[NO]LOG_FILE[:filespec] /[NO]MASS_INSERT /MERGE /RELATIVE /[NO]REPLACE The CONVERT command invokes the RMSCNV utility which moves records from one file to another. RMSCNV reads records from an input file and writes them to an output file. The action of RMSCNV depends on the organization - sequential, relative, or indexed - of the two files, and on the qualifiers you include in the CONVERT command. See HELP CONVERT FILESPECS for information on infile and outfile and HELP CONVERT qualifier. See also HELP CONVERT EXAMPLES. 2 INFILE #FILESPEC 2 OUTFILE #FILESPEC 2 FILESPEC CONVERT[/qualifier[s]] infile outfile infile Specifies the file that is the source of records to be written to the output file. CONVERT reads input records sequentially, regardless of the organization of the input file. No wildcards permitted. outfile Specifies the file that is to receive the records from the input file. The default file organization for the output file is sequential. If the output file is not sequential, use the /RELATIVE or /INDEXED qualifier to indicate the organization. If the output file is to be sequential, CONVERT can create the file; it need not exist prior to your entering the CONVERT command. CONVERT cannot create indexed or sequential files; these must have been created prior to your entering the CONVERT command. No wildcards permitted. 2 NOAPPEND #APPEND 2 APPEND CONVERT/APPEND infile outfile Specifies that you wish RMSCNV to append records to the end of an existing sequential file. If the output file is not sequential, RMSCNV ignores the qualifier. You cannot use both /APPEND and /REPLACE in the same command line. The default is /NOAPPEND, but the action taken depends on the presence of the /REPLACE qualifier in the command line. If you specified /REPLACE, RMSCNV performs the replace operation. If you did not specify /REPLACE, RMSCNV creates the next higher version of the file. This qualifier is the equivalent of the /AP switch in an RMSCNV command line. 2 BLOCK_SIZE CONVERT/BLOCK_SIZE:n infile outfile Specifies the physical block size of an output file being created on magtape. n can be from 18 through 8192 characters. RMSCNV rounds this value up to the next multiple of 4. If you do not specify this qualifier, the default tape block size is 512 characters. This qualifier is the equivalent of the /BL switch in an RMSCNV command line. 2 NOFIXED_CONTROL #FIXED_CONTROL 2 FIXED_CONTROL CONVERT/[NO]FIXED_CONTROL infile outfile The /FIXED_CONTROL qualifier directs RMSCNV to handle variable-with-fixed-control (VFC) format records in either the input file or the output file. If the fixed-control area of the input file and the output file are the same size, RMSCNV performs a straightforward copy. See the RMS-11 documentation supplied with your system for information on how RMSCNV handles other combinations. If you include this qualifier and neither file specifies VFC records, RMSCNV terminates. This qualifier is the equivalent of the /WF switch in an RMSCNV command line. The default is /NOFIXED_CONTROL. This means that if one of the named files contains VFC records, the fixed-control area of each record is ignored. That is, if the input file includes VFC records and the output file does not, only the variable portion of each record is written to the output file; if the output file includes VFC records and the input file does not, data is written only into the variable portion of each output record. 2 NOIDENTIFICATION #IDENTIFICATION 2 IDENTIFICATION CONVERT/[NO]IDENTIFICATION infile outfile Requests that RMSCNV print its current version number and patch level on your terminal. See the RMSCNV documentation for more information. This qualifier is the equivalent of the /ID switch in an RMSCNV command line. The default is /NOIDENTIFICATION. 2 INDEXED CONVERT/INDEXED infile outfile The /INDEXED qualifier informs RMSCNV that the output file is of indexed organization. Regardless of their organization, all input files are read sequentially. RMSCNV reads each record from the input file, then applies the output file's record format, that is, key placement within the record, to the data. If you do not specify the /KEY qualifier with a value, the key of reference is the primary key; otherwise, it is the key you specify. This qualifier is the equivalent of the /FO:IDX switch in an RMSCNV command line. 2 KEY CONVERT/KEY[:n] infile outfile Indicates the key that establishes the order in which records are read sequentially from an indexed input file and written to the output file. n can be from 0 through 9. The default is n=0 and indicates the primary key; n=1 is the first alternate key; n=9 is the ninth alternate key. This qualifier is the equivalent of the /KR switch in an RMSCNV command line. 2 NOLOG_FILE #LOG_FILE 2 LOG_FILE CONVERT/[NO]LOG_FILE[:filespec] infile outfile Directs RMSCNV to summarize processing in a log. If you do not include a filespec, the log appears on your terminal. If you name a file, that file will be created and written to by RMSCNV. The log includes the following elements: The command string in RMSCNV format. This will not be the same as DCL format. Copies of all error messages produced during execution. An indication of any duplicate-key problems. If the log is appearing on the terminal, the indications consists only of the following message: SOME DUPLICATE RECORDS NOT WRITTEN If the log is being written to a file, RMSCNV supplies the indicator DUP RCD= followed by the first 72 characters of the record that could not be written. This qualifier is the equivalent of the /SL switch in an RMSCNV command line. The default is /NOLOG meaning that only normal error messages appear on your terminal. 2 NOMASS_INSERT #MASS_INSERT 2 MASS_INSERT CONVERT/[NO]MASS_INSERT infile outfile Directs RMSCNV to activate the RMS-11 mass insert I/O technique and then use sequential put operations to insert records into the output file. This is the equivalent of the /MA switch in an RMSCNV command line. The default for nonsequential file organization is /NOMASS_INSERT. 2 MERGE CONVERT/MERGE infile outfile Directs RMSCNV to copy records from the input file into the output file. Both files must be of the same organization. 2 PAD CONVERT/PAD[:[#]arg] infile outfile Directs RMSCNV to pad records read from the input file to the output file's record length before writing them to the file. If you specify the qualifier without an argument, the pad character is null. If you do not include the number sign (#), the argument can be any printing ASCII character except the number sign, question mark (?), or commercial at-sign (@). If you include the number sign (#), n can be an octal number between 0 and 377, representing the full ASCII character set. This enables you to use the three excluded characters as pad characters by specifying 43 for #, 77 for ?, and 100 for @. Use this qualifier only when the output file specifies fixed-length records. This qualifier is the equivalent of the /PD switch in an RMSCNV command line. 2 RELATIVE CONVERT/RELATIVE infile outfile The /RELATIVE qualifier informs RMSCNV that the output file is of relative organization. Regardless of their organization, all input files are read sequentially. The /RELATIVE qualifier is the equivalent of the /FO:REL switch in an RMSCNV command line. RMSCNV reads records from the input file and writes them into successive record cells of the output file, beginnig with cell 1. If RMSCNV encounters a cell containing a record, it terminates with an error message. All records written to that point are in the output file. You should examine the two files to determine how far the processing went. 2 NOREPLACE #REPLACE 2 REPLACE CONVERT/[NO]REPLACE infile outfile The /REPLACE qualifier directs RMSCNV to supersede an existing sequential file. RMSCNV replaces a file in the output account with the same file name, type, and version number. You cannot use /REPLACE and /APPEND in the same command line. The /REPLACE qualifier is the equivalent of /SU in an RMSCNV command line. The default is /NOREPLACE, but the default action depends on whether the command line includes an /APPEND or not. If you specify /APPEND, RMSCNV performs the append operation. If you do not specify /APPEND, RMSCNV creates the next higher version of the file. 2 SEQUENTIAL CONVERT/SEQUENTIAL infile outfile The /SEQUENTIAL qualifier informs RMSCNV that the output file is of sequential organization. Regardless of their organization, all input files are read sequentially. The default output file organization for RMSCNV is sequential. This qualifier is the equivalent of the /FO:SEQ switch in an RMSCNV command line. If you do not specify either the /APPEND or /REPLACE qualifier, the output file need not exist before you issue the CONVERT command. If the output file does not exist RMSCNV creates the output file with the record attributes of the input file. RMSCNV then reads records from the input file and writes them sequentially into the new output file. If the output file already exists, and the command does not include the /APPEND qualifier, RMSCNV creates the next higher version of the file. RMSCNV then reads records from the input file and writes them sequentially into the new version of the output file. If the output file exists and you specify the /APPEND qualifier, RMSCNV reads records from the input file and writes them sequentially into the output file, starting with the beginning of the file. If the output file exists and you specify the /REPLACE qualifier, RMSCNV reads records from the input file and writes them sequentially into the output file, starting with the record postion following the last record already in the file. 2 NOTRUNCATE #TRUNCATE 2 TRUNCATE CONVERT/[NO]TRUNCATE infile outfile Directs RMSCNV to truncate records read from the input file to the output file's record length before writing them into the output file. The trailing bytes of the record are truncated. The default is /NOTRUNCATE. If you do not specify /TRUNCATE and the imput records are too long, RMSCNV terminates with the following error message: CON -- INPUT AND OUTPUT RECORD SIZES DO NOT CORRESPOND 2 EXAMPLES >CONVERT Input file? FOO.BAR Output file? POOH.BAR The output file does not exist. RMSCNV creates the sequential file POOH.BAR and copies the records from FOO.BAR into it. >CONVERT FOO.BAR POOH.BAR This example is the equivalent of the previous one. >CONVERT/INDEXED GRIZZLY.BAR CROW.BAR RMSCNV reads each record of the input file GRIZZLY.BAR sequentially and examines the contents in the primary key field, which is defined as an attribute of CROW.BAR. RMSCNV then inserts the record into CROW.BAR. >CONVERT/RELATIVE/KEY:1 SAND.BAR MAX.BAR RMSCNV reads the indexed input file SAND.BAR, using the first alternate key of the file to establish the sequence of access. Then RMSCNV writes the records sequentially into an empty relative output file MAX.BAR, starting with record cell 1. Note that the /RELATIVE qualifier refers to the organization of the output file and the /KEY qualifier refers to the organization of the input file. >CONVERT/APPEND/SEQUENTIAL/KEY:2 RUNNING.BAR CORNER.BAR RMSCNV reads the indexed input file RUNNING.BAR, using the second alternat key of the file to establish the sequence of access. Then RMSCNV appends the records at the end of the existing sequential output file CORNER.BAR. If the /APPEND qualifier had not been specified, RMSCNV would have created the next higher version of CORNER.BAR and written the records from RUNNING.BAR into it. >CONVERT/RELATIVE/FIXED_CONTROL MAMA.BAR PAPA.BAR RMSCNV reads fixed-length records from the indexed input file MAMA.BAR, using (by default) the primary key of the file to establish the sequence of access. The RMSCNV writes the records sequentially in a VFC format into the existing relative file PAPA.BAR. Record format is an attribute of each file. As each record is written, the first bytes become the fixed control area. >CONVERT/TRUNCATE/BLOCK_SIZE:1024/APPEND/KEY:9 BRER.BAR Output file? MM3:BRER.BCK RMSCNV reads the indexed input file BRER.BAR, using the file's ninth alternate key to establish the sequence of access. The RMSCNV writes the records to magnetic tape, truncating them to the output file's record length before adding them to the end of the existing file, and formatting the tape blocks to 1024 bytes each.