! Extract.Hlp ! Pat Rankin, Apr'89 ! Online help for EXTRACT. ! 1 EXTRACT General purpose file extraction utility. Selects records from the beginning, middle, or end of one or more files and optionally performs various modifications before writing them out. format: EXTRACT 'options' file,... EXTRACT /RECORD=([START=m,END=n,COUNT=k]) file,... EXTRACT /HEAD=k file,... EXTRACT /TAIL=k file,... 2 Parameter file[,...] input file(s); wildcards are supported. All output is written to a single file (default is SYS$OUTPUT) even if multiple input files are specified. 2 Qualifiers /BLOCKS /BLOCKS[=(option,...)] Similar to DUMP/BLOCKS; extracts blocks from the input file(s) without interpreting their record structure. Up to two of the following options may be specified; if more than one is used, separate them with a comma and enclose the list in parentheses. START=m starting block number; the first block in the file is 1. A negative value specifies a number of blocks relative to the end of the file: -1 is the last block, -2 is the one before that, etc. END=n ending block number; the last block of the file is considered to be block number -1. COUNT=k number of blocks to extract. If START is specified, END is derived by adding COUNT-1 to it; if END is specified, START is derived by subracting COUNT-1 from it; if neither is specified, START is 1 and END is set to COUNT. Incompatable with /RECORDS, /HEAD, and /TAIL. Also incompatable with /COLUMNS, /EXPAND_TABS, /TRANSLATE, and /VFC_HEADER. /COLUMNS /COLUMNS=([-,]column_range,...) Select or reject certain columns within extracted records before writing them to the output file. 'column_range' is either a single column number or a low and high pair separated by "-" or ":". If more than one range is desired, separate them with commas and enclose the list in parentheses. If the first element of the list is "-", then the rest of the list represents columns to reject rather than ones to select. If the first range begins with ":" (ie, ":20") then column 1 is implied; if the last range ends with ":" (ie, "41:") or ":*" then the end of the record is implied. Note: the output record consists of the selected columns in their original relative positions, not in the order listed in /COLUMNS. That is, /COLUMNS=(25:30,5:10) produces the same output as the list (5:10,25:30). /EDIT /EDIT=(option,...) Perform one or more of various modifications to extracted records before writing them to the output file. The available functions include all options of the DCL F$EDIT() lexical function plus several extensions: COLLAPSE, COMPRESS, LOWERCASE, TRIM, UNCOMMENT, UPCASE, STRIP_TRAILING, IGNORE_QUOTES, FALLBACK, FORMAT. If more than one option is specified, separate them with commas and enclose the list within parentheses. See "edit_options" for more information. /EXPAND_TABS /[NO]EXPAND_TABS Convert ASCII tab characters into spaces. Tab stops are considered to be positioned at every 8th column: 9, 17, 25, ... By default, tabs are expanded if extraction by columns (/COLUMNS=xxx) or translation into EBCDIC (/TRANSLATE=ASCII_TO_EBCDIC) is requested, and left as tabs otherwise. Tab expansion is never performed if translation from EBCDIC into ASCII (/TRANSLATE=EBCDIC_TO_ASCII) is requested. /HEAD /HEAD[=count] Extract records from the beginning of the file(s). 'count' is the number of records to extract; if not present, the default value is 22. A negative 'count' value designates the number records at the end of the file to omit. That is, /HEAD=-5 will extract every record in the file except for the last 5. Incompatable with /BLOCKS, /RECORDS, and /TAIL. /IDENTIFY /[NO]IDENTIFY Determines whether to display the input file name before performing extraction upon its contents. By default, the file identification is performed if the input file specification is a list of files, contains any wildcards, or includes a search list. /IDENTIFY forces identification; /NOIDENTIFY suppresses identication. Note: the file identification is written to the same destination as the extracted data, so it should normally be suppressed if the data is being translated into EBCDIC or if vfc-headers are kept. /OUTPUT /OUTPUT[=file] Specifies the output file. Output is written to SYS$OUTPUT by default. File format is variable length records with implied carriage return (ie, standard text file format), unless whole records are extracted from a file having fixed length records. /VFC_HEADER=KEEP will produce a VFC format output file (but only if the input file has VFC format). /RECORDS /RECORDS[=(option,...)] Similar to DUMP/RECORDS but with more flexibility in indicating which records. Extracts specified records from the input file(s). Up to two of the following options may be specified; if more than one is used, separate them with a comma and enclose the list in parentheses. START=m starting record number; the first record in the file is 1. A negative value specifies a number of records relative to the end of the file: -1 is the last record, -2 is the one before that, etc. END=n ending record number; the last record of the file is considered to be record number -1. COUNT=k number of records to extract. If START is specified, END is derived by adding COUNT-1 to it; if END is specified, START is derived by subracting COUNT-1 from it; if neither is specified, START is 1 and END is set to COUNT. Incompatable with /BLOCKS, /HEAD, and /TAIL. /TAIL /TAIL[=count] Extract records from the end of the file(s). 'count' is the number of records to extract; if not present, the default value is 22. A negative 'count' value designates the number records at the start of the file to omit. That is, /TAIL=-5 will extract the entire file except for the first 5 records. Incompatable with /BLOCKS, /RECORDS, and /HEAD. /TRANSLATE /TRANSLATE={ ASCII_TO_EBCDIC | EBCDIC_TO_ASCII } Translate data (which is assumed to represent simple character text) from ASCII into EBCDIC or vice versa. One of the two keywords must be specified. If ASCII_TO_EBCDIC is used then tab expansion is done unless /NOEXPAND_TABS is specified. If the reverse is used, no tab expansion will be attempted regardless of /expand_tabs. Translation from EBCDIC into ASCII is done before any modifications from /EDIT are performed; translation from ASCII into EBCDIC is done after any requested edits are performed. /VFC_HEADER /VFC_HEADER={ IGNORE | DATA | KEEP } Specifies how to handle files in variable-with-fixed-control-area format (such as batch .log files). By default, the control area is ignored. /VFC_HEADER=DATA causes the control area, which is normally hidden, to be treated as part of the normal record contents. A value of KEEP causes the output file to have the same format as the input file (rather, as the *first* input file if there is more than one). If the [first] input file is not in VFC format, /VFC_HEADER=KEEP has no effect. !/TRUNCATE -- not implemented !/WIDTH -- not implemented !/WRAP -- not implemented 2 edit_options Options available for /EDIT: COLLAPSE -- remove all spaces and tabs COMPRESS -- convert multiple spaces and tabs into a single space LOWERCASE -- convert unquoted letters into lower-case TRIM -- remove leading and trailing blanks (spaces and tabs) UNCOMMENT -- remove comments (from "!" to end of line) UPCASE -- convert unquoted letters into upper-case STRIP_TRAILING -- remove trailing blanks (spaces and tabs) IGNORE_QUOTES -- don't check quotes ("xxx") when doing edits FALLBACK -- strip 8-bit data into 7-bit equivalent FORMAT -- convert non-visible (control) characters into "." If both UPCASE and LOWERCASE are specified, UPCASE takes precedence. COLLAPSE supercedes COMPRESS and TRIM; TRIM supercedes STRIP_TRAILING. Quoted text is subject to FALLBACK and FORMAT modifications regardless of whether or not IGNORE_QUOTES is specified. 2 examples !Display the last 10 lines of Login.Com on the terminal $ EXTRACT/TAIL=10 Login.Com /IDENTIFY !Look at the first few lines of all Fortran source files $ EXTRACT/HEAD=5 *.For !Copy Test.Txt to Test.Dat, converting text into upper case ! and removing excess blanks. $ EXTRACT/EDIT=(UPCASE,COMPRESS) Test.Txt/OUTPUT=Test.Dat !Extract all but the first 10 and last 10 records of Test.Dat $ EXTRACT Test.Dat/RECORDS=(START=11,END=-11) /OUTPUT=Test.Mid !Get specific columns out of several files $ EXTRACT/COLUMNS=(1:10,18:19,25,41:*) Test.*,[...]*.Tmp !#eof#