FCOPY FROM COMMAND

Copies data from one file to another.

 

   > FROM= [fromfile] ;TO= [tofile] [;functionlist]

The FROM command specifies the file from which data is copied and the file to which it is copied. It optionally includes one or more function specifications in the functionlist parameter.

PARAMETERS

fromfile

Specifies the file to be copied. For a KSAM file this should be the actual file designator. An asterisk (*), indicating the "from" file designated in the immediately preceding FCOPY command should not be used to copy KSAM files. If fromfile is omitted, the standard input device $STDIN is assumed.

tofile

Specifies the file to receive the data. For a KSAM file this should be the actual file designator. If tofile is specified as (dfile,kfile) where dfile is a data file name and kfile is a key file name, a new KSAM file is created with the same characteristics as the fromfile. The data and key values are copied from the existing file to the new file excluding any data records tagged for deletion.

If tofile is omitted, the standard list device $STDLIST is assumed. Using this device as a "tofile" is a good way to display the contents of a KSAM file at your terminal during a session and on the line printer in a batch job.

functionlist

One or more keyword parameters separated by semicolons that specify particular FCOPY functions. (Refer to Table 2-4 “FCOPY Functions with KSAM Files” for a complete list.)

KSAM OPTIONS

Two keyboard options may be used with FCOPY to copy KSAM files: the KEY= option and the NOKSAM option. These two options are mutually exclusive; they cannot both be specified in the same FCOPY FROM command. When neither option is specified, the KSAM fromfile is copied to another file in primary key sequence. This is exactly like copying any HP 3000 file to another with FCOPY.

Table 2-5 “KSAM Options of FCOPY” summarizes the results of using, or omitting, the KSAM options KEY= and NOKSAM.

KEY= OPTION. KEY= specifies a key whose value determines the sequence in which the file is copied. The object of KEY= is a positive integer that identifies the key by its starting character location in the data file. The indicated key may be either the primary or an alternate key. If the object of KEY= is zero, then the file is copied in chronological sequence rather than in key sequence.

If KEY= and NOKSAM are both omitted, the KSAM file is copied in primary key sequence. In this case and in the case where KEY= is specified, only active records, not those tagged for deletion are copied.

Table 2-4 FCOPY Functions with KSAM Files

FUNCTION LIST ENTRY* ACTION PERFORMED

;KEY=nn Copy active records from KSAM file in sequence by key located at nn; if omitted, copy file in primary key sequence; if nn is zero, copy file in chronological order. The KSAM EOF is used.

;NOKSAM Copy all records, including deleted records, from data file of KSAM file to any other file. Copy is in chronological sequence; records must be fixed length. The data file being copied is opened as an MPE file and the MPE end-of-file is used. Unless the TO file is an MPE file created with l user label, specify NOUSER LABELS.

;NEW Copy active records and associated key values from KSAM file to new KSAM file specified as TO= (dfile,kfile).

{;EBCDICIN 

 ;BCDICIN}

Translate copied data from EBCDIC to BCDIC code to ASCII.

{;EBCDICOUT 

 ;BCDICOUT}

Translate copied data from ASCII code to EBCDIC or BCDIC.

;UPSHIFT

Convert any copied lower-case characters to uppercase.

;SUBSET={"string" 

         #pattern#}[,[column] 

                                                         [,EXCLUDE] ]

Copy from data file only records containing specified "string" or #pattern# starting search in specified column or column 1. If EXCLUDE specified, copy all data file records except those containing "string" or #pattern#

;SUBSET=[first-record] [ {,#records 

                                                      :last record} ]

Copy from data file as many records as are specified in #records starting with first-record; or copy from first-record through last-record inclusive. If first-record omitted, start at first sequential record in file; if #records or last-record omitted, copy through last sequential record in file.

;VERIFY [=#errors] Verify accuracy of copy where both files are on disc; terminate if #errors exceeded;

;COMPARE [= #errors] Compare without copying the fromfile to the tofile; terminate if differences exceed #errors. Comparison applies only to KSAM data files.

;OCTAL [;CHAR] [;NORECNUM] [;TITLE="title"] Display contents of "from" file as octal images on a word-by-word basis.

;HEX [;CHAR] [;NORECNUM] [;TITLE="title"] Display contents of "from" file as hexadecimal images on a word-by-word basis.

;CHAR [ {;OCTAL

         ;HEX} ] [;NORECNUM] 

                 [;TITLE="title"]

Display contents of "from" file as character images on a word-by-word basis.

*IGNERR, SKIPEOF, and SUBSET without parameters do not apply to "from" files.

Table 2-5 KSAM Options of FCOPY

OPTION	RESULT
KEY=omitted	Copy KSAM file in primary key sequence.
KEY=n (n>0)	Copy KSAM file in sequence by the key (primary or alternate) located starting at character n of each data record (counting from first character = 1).
KEY=0	Copy KSAM file in chronological sequence (the sequence in which records were actually stored in the file); copy excludes records marked for deletion.
NOKSAM	Copy the data file of a KSAM file to any file in chronological sequence; copy includes records marked for deletion.

NOKSAM OPTION. NOKSAM allows you to copy the data file of a KSAM file with fixed-length records to any MPE file, including KSAM files. All indicated records of the data file are copied, including those tagged for deletion. When you copy a file using the NOKSAM option, you should also specify the NOUSERLABELS option. The only exception to this rule is if the TO file is an MPE file that you have already created with one user label.

USING FCOPY

FCOPY is useful in order to compact a KSAM file that has many records tagged for deletion. When a file has been used for a period of time, changes and deletions may result in a high percentage of inactive records. In order to recover the space occupied by such records, you can copy the file to a new file with FCOPY. Since FCOPY copies only active records, records that are not tagged for deletion, the new KSAM file has no unused space embedded among the data records.

FCOPY can also be used to recover records tagged for deletion in a KSAM file. The FCOPY NOKSAM option copies all records including those tagged for deletion. The first two characters of such records will contain the delete code rather than their original values, but otherwise are recovered intact. This can be a useful feature in order to recover records deleted by mistake.

Another use of FCOPY is to reload data from a damaged file to a new file. This may be required as a result of a system failure. If you decide to reload a KSAM file following a system failure, you should first run the KEYINFO command of KSAMUTIL to reset the end-of-file markers and delete any invalid key values. If the file is still damaged and you choose to reload it, you should use FCOPY to transfer existing records to a new undamaged KSAM file. In this case, you use the KEY=0 option rather than the NOKSAM option, unless you want to keep all the deleted records or the key file was lost.

FCOPY WITH NO OPTIONS. Assume a file named KSAMFILE created with one primary key, an integer located at character 21. Since many records were tagged for deletion in the file, it is time to copy the active records to a new file, You may either create a new KSAM file with the BUILD command as shown in example 1, or use FCOPY to create the new KSAM file as shown in example 2. In either case, you should purge the original file (KSAMFILE in the examples) and then rename the new file (KSAMFIL2) with the data and key file names of the original file so that any programmatic references to the file need not be changed.

You may also use FCOPY to create an empty KSAM file with all the characteristics of an existing file, but with no data. The method for doing this is shown in example 3.

Create new file with BUILD:

 

:RUN KSAMUTIL.PUB.SYS 

>BUILD KSAMFIL2;KEYENTITY =KFIL2;KEY=I,21,2 <-------- create "to"file 

>EXIT 

:RUN FCOPY.PUB.SYS 

>FROM=KSAMFILE;TO=KSAMFIL2 <----------- copy in primary key sequence 

>EXIT 

:RUN KSAMUTIL.PUB.SYS 

>PURGE KSAMFILE <----------------- purge "from" file after copy 

KSAMFILE.KSAM.DATAMGT & KFILE PURGED 

>RENAME KSAMFIL2,KSAMFILE--  

                          | <--------- rename copied file with old file names 

>RENAME KFIL2,KFILE      --

>EXIT 

:

Use FCOPY to create new file:

 

:RUN FCOPY.PUB.SYS 

>FROM=KSAMFILE;TO=(KSAMFIL2,KFIILE2) 

>EXIT 

:RUN KSAMUTIL.PUB.SYS 

>PURGE KSAMFILE 

KSAMFILE.KSAM,DATAMGT & KFILE PURGED 

>RENAME KSAMFIL2,KSAMFILE 

>RENAME KFILE2,KFILE 

>EXIT 

:

You may specify the ;NEW function in the FCOPY FROM command for purposes of documentation. Its inclusion or omission does not affect the command in any way.

This method not only creates the new KSAM file, but also copies all the data from the existing file to the new file (except records marked for deletion). Example 3 below, shows how you can create a KSAM file with exactly the same specifications as an existing file but with no data.

Use FCOPY to build a new file with no data:
:RUN FCOPY.PUB.SYS >FROM=KSAMFILE; TO=(KSAMFIL3,KFILE3); SUBSET=1,0 <---- copy 0 records 0 RECORDS PROCESSED*** 0 ERRORS
The new file, KSAMFIL3, is created with exactly the same specifications as the existing file KSAMFILE, but with no data. This is easier than building the file with the BUILD command, but should be used only if the new file is to have keys in the same position and the same length as the existing file.
Following any of these operations, only active records are contained in the new KSAM files. These records are stored in primary key sequence in the data file; that is, the new chronological and the primary key sequences axe the same. If you prefer to maintain the original chronological sequence, then you can use the KEY=0 option.
Use FCOPY to add data to an existing file:
Before running FCOPY to add new records to a file that contains data, make sure that file (the TO file) is opened for either APPEND or INOUT access. Otherwise, FCOPY will open the TO file for write-only access causing the end-of-file to be reset to zero and any existing data to be lost. For example:
:FILE A = KSAMFILE,OLD;ACC = APPEND or ACC = INOUT :RUN FCOPY.PUB.SYS >FROM = NEWDATA ;TO = *A
The data in the file NEWDATA is appended to the data in the existing file, KSAMFILE, in primary key sequence (the default).

FCOPY WITH KEY = OPTIONS.

Assume that a company's employee records have been maintained in sequence by social-security-number in a KSAM file, EMPLOY, but a new policy requires that they be maintained in sequence by employee number. FCOPY can be used to transfer the data to a new file, EMPLOY2, in which all employees are re-ordered by their unique employee numbers.

Assume EMPLOY was created with the following command:

 

   :RUN KSAMUTIL.PUB.SYS 

   >BUILD EMPLOY;REC=3000;KEYENTITY =EMPKEY;& 

   >      KEY=B,3,11;& <--------------- primary key (social-security-number) 

   >      KEY=B,14,5;& <------------ alternate key (employee number) 

   >      KEY=B,19,30,,DUP <------ alternate key (name) 

   >EXIT

Before copying and resequencing file EMPLOY, a new KSAM file is built:

 

   :RUN KSAMUTIL.PUB.SYS 

   >BUILD EMPLOY2;REC=3000;KEYENTITY =EMPKEY2;& 

   >      KEY=B,14,5;& <------------ primary key (employee number) 

   >      KEY=B,19,30,,DUP <----- alternate key (name) 

   >EXIT

There is no need for the new key file to retain the same structure as the key file of the copied file. The primary key in EMPLOY has been dropped from EMPLOY2; although the socialsecurity-number remains in the data file, it is no longer a key. An alternate key in EMPLOY, the employee's identification number, is the primary key in EMPLOY2.

Once the new KSAM file has been created, you can copy the old file EMPLOY to the new file EMPLOY2 in the new sequence:

 

   :RUN FCOPY.PUB.SYS 

   >FROM=EMPLOY;TO=EMPLOY2;KEY=14 

   >EXIT                        ↑ 

                                |

                 column number of key used to sequence EMPLOY2

To avoid changing programs that reference the file EMPLOY, you can rename EMPLOY2 with the name EMPLOY, first purging the old file EMPLOY:

 

   :RUN KSAMUTIL.PUB.SYS 

   >PURGE EMPLOY 

   KSAMFILE EMPLOY.KSAM.DATAMGT & EMPKEY PURGED 

   >RENAME EMPLOY2,EMPLOY <-------------- rename data file 

   >RENAME EMPKEY2,EMPKEY <-------------- rename key file 

   >EXIT

Another use of FCOPY is to copy a selected portion of one KSAM file to another. For example, using the same file EMPLOY used in previous examples, you can copy all the employee records whose last names begin with the letter A into a new file sequenced by employee name:
:RUN KSAMUTIL.PUB.SYS >BUILD EMPLOYA;KEYENTITY =AKEY;KEY=B,19,30,,DUP >EXIT :RUN FCOPY.PUB.SYS >FROM=EMPLOY;TO=EMPLOYA;KEY=19;SUBSET="A",19 >EXIT
The new file EMPLOY is sequenced by the key starting in column 19 (employee name) and only contains records for employees whose last names start with A.
If you want to copy the KSAM file in chronological sequence, you can use the KEY=0 option. Since this option copies only active records, it can be used to compact a file in which many records are tagged for deletion while retaining the chronological order in which the file was created. It is also the preferred option for reloading a KSAM file after a system failure.
Assume the new file EMPLOYX has the identical structure to the file EMPLOY used in the previous examples:
:RUN FCOPY.PUB.SYS >FROM=EMPLOY;TO=EMPLOYX;KEY=0 >EXIT
The new file is identical in its chronological sequence to the old file, but contains only active records.
To find out how many records are currently active in a KSAM file, you can use FCOPY as follows:
:RUN FCOPY.PUB.SYS > FROM=KSAMFILE ;TO=$NULL N RECORDS PROCESSED *** 0 ERRORS (where N is the number of active records in the KSAM file) >EXIT
Only the active records (those not marked for deletion) will be listed as present in the file. (You can also calculate the number of active records by looking at the VERIFY listing, option 3, and subtracting the number of FREMOVEs from the FWRITES.)

FCOPY WITH NOKSAM OPTION.

Using NOKSAM, you can copy the data file of a KSAM file to another file. The records are copied in chronological sequence. Since NOKSAM copies records marked for deletion as well as active records, it provides a method for recovering the data in any records marked for deletion. For example, if certain records in file EMPLOY were incorrectly marked for deletion, the NOKSAM option could be used to copy the entire data file to a new file including the inactive records.

Using the SUBSET parameter of FCOPY, you can copy only those records marked for deletion. In the following example, all deleted records are listed on the line printer:

 

                     pattern of all 1's in 1st 2 characters 

                                |

:FILE X; DEV=LP                 |

:RUN FCODY.PUB.SYS            /---------/

>FROM=EMPLOY;TO=*X;SUBSET=#%377,%377#,1;NOKSAM;OCTAL;CHAR;NORECNUM;&

>TITLE="RECOPDS DELETED FROM THE FILE, EMPLOY"

When records are deleted from a KSAM data file, a pattern of all 1's is written to the first two characters of the deleted record. (ln each character this pattern can be represented as the octal value %377.) If you want to be able to recover key data from deleted records in this manner, you should avoid placing key data in the first two characters of a data record.

Note that you should not use the NOKSAM option to copy a KSAM file with variable-length records to another KSAM file. Also, if NOKSAM must be used to reload a file after a system crash (for instance, because the key file was lost), you should use the SUBSET option to copy only valid records. Normally, you use the KEY=0 option to reload KSAM files after a system failure.

(Refer to appendix E, Recovery From System Failure, for a full discussion of using FCOPY to reload a KSAM file following a system failure.)

COPYING VARIABLE-LENGTH KSAM FILES

You can copy a variable-length KSAM data file by first copying it to an MPE file and then copying the MPE file to a new KSAM file.

First use the MPE :LISTF,2 command to list the attributes of the KSAM data file. Then use the MPE :BUILD command to build an MPE file with a record length two words less than that of the KSAM data file, a blocking factor the same as the data file (always 1), variable-length records, and the same record limit as the KSAM data file.

Copy the KSAM data file to the MPE variable-length file on a block-by-block basis, as follows:

 

   :FILE DATAFILE; NOBUF 

   :FILE MPEFILE; NOBUF 

   :FCOPY FROM= *DATAFILE; TO= *MPEFILE; NOKSAM;NOUSERLABELS

Copy the variable-length records from the MPE file to a newly created KSAM file omitting the deleted records.

 

   FCOPY FROM= MPEFILE;TO= KSAMFILE;SUBSET= #%377,%377#,,EXCLUDE

DISPLAY COPIED FIIES ON $STDLIST. When you omit the "to" file from the TO= specification, the standard output device is assumed. This allows you to list the contents of the KSAM file at your terminal in a session or on the line printer in a job.

Assume the file JNAMES with a primary key (last name) starting in character 11 and three alternate keys: a phone number starting in character 21, a city name starting in character 53, and a zip code starting in character 67.

If KEY= is omitted, the file is listed in primary key, order:

 

>FROM=JNAMES;TO=) 

JEANNE   /ALOGICAL   226-0295 4942  COUSIN CT         SUNNYVALE    95054 

POLLY    |CHROMATIC  267-1412 1148  COLORFUL CT       SAN JOSE     95130 

ANNA     |FORA       253-5246 9283  TROCHAIC TRAIL    SAN JOSE     95131 

ANNE     |HOWE       372-4328 6547  EXUBERANCE WY     CAMPBELL     95112 

HY       |KUVERSE    267-8961 650   LOTUS BLOSSOM WY  SAN JOSE     95136 

ANNA  |--|LOGUE      224-8934 1707  INVERSE WY        MOUNTAINVIEW 95051 

ARTHUR|  |MOMITER    443-5346 1554  MERCURY ST.       MILPITAS     94173 

CLARA |  |NETTE      243-4493 2667  GOODMAN DR        ALVISO       95143 

RHEA  |  |PREYSELLE  365-8551 10879 REVIEW ROAD       SAN JOSE     95070 

KURT  |  |REMARQUE   243-1043 34    BRIEF ST          MILPITAS     94062 

MIKE  |  |ROMETER    269-1712 1681  MACHINIST         SUNNYVALE    95112 

TRUDY |  \TEKTIFF    255-1005 17155 POIROT PL         CAMPBELL     95121 

EOF FOUND IN FROMFILE AFTER RECORD 11 

      | 

      | 

12 RECORDS PROCESSED *** 0 ERRORS 

      | 

      | 

      | 

      ascending order by primary key

Use SUBSET to list selected portions of the file, for example, to list the first two records in primary key sequence:

 

       >FROM=JNAMES;TO=;KEY=11;SUBSET=0,2 

       JEANNE    ALOGICAL  226-0295 4942  COUSIN CT    SUNNYVALE   95054 

       POLLY     CHROMATIC 267-1413 1148  COLORFUL CT  SAN JOSE    95030 



                 2 RECORDS PROCESSED *** 0 ERRORS

If KEY="primary key location", the file is listed in primary hey order:

 

>FROM=JNAMES;TO=;KEY=11 

JEANNE    ALOGICAL   226-0295 4942  COUSIN CT         SUNNYVALE    95054 

POLLY     CHROMATIC  267-1412 1148  COLORFUL CT       SAN JOSE     95130 

ANNA      FORA       253-5246 9283  TROCHAIC TRAIL    SAN JOSE     95131 

ANNE      HOWE       372-4328 6547  EXUBERANCE WY     CAMPBELL     95112 

HY        KUVERSE    267-8961 650   LOTUS BLOSSOM WY  SAN JOSE     95136 

ANNA      LOGUE      224-8934 1707  INVERSE WY        MOUNTAINVIEW 95051 

ARTHUR    MOMITER    443-5346 1554  MERCURY ST.       MILPITAS     94173 

CLARA     NETTE      243-4493 2667  GOODMAN DR        ALVISO       95143 

RHEA      PREYSELLE  365-8551 10879 REVIEW ROAD       SAN JOSE     95070 

KURT      REMARQUE   243-1043 34    BRIEF ST          MILPITAS     94062 

MIKE      ROMETER    269-1712 1681  MACHINIST         SUNNYVALE    95112 

TRUDY   |>TEKTIFF    255-1005 17155 POIROT PL         CAMPBELL     95121 

EOF FOUND IN FROMFILE AFTER RECORD 11 

        |

        |

12 RECORDS PROCESSED *** 0 ERRORS 

        |

        |

        |

        |byte location 11 (same sequence as previous example)

If KEY="alternate key location", the file is listed in sequence by that key:

 

>FROM=JNAMES;TO=;KEY=67  

KURT    REMARQUE   243-1043 34    BRIEF ST          MILPITAS      /94062 

ARTHUR  MOMITER    443-5346 1554  MERCURY ST        MILPITAS      |94173 

DOLLY   CHROMATIC  267-1413 1148  COLORFUL CT       SAN JOSE      |95030 

ANNA    LOGUE      224-9934 1707  INVERSE WY        MOUNTAIN VIEW |95051 

JEANNE  ALOGICAL   226-0295 4942  COUSIN CT         SUNNYVALE     |95054 

RHEA    PREYSELLE  365-9551 10879 REVIEW ROAD       SAN JOSE      |95070 

ANNE    HOWE       372-4328 6547  EXUBERANCE WY     CAMPBELL      |95112 

MIKE    ROMETER    269-1712 1681  MACHINIST DR      SUNNYVALE     |95112 

TRUDY   TEKTIFF    255-1005 17155 POIROT PL         CAMPBELL  |---|95121 

ANNA    FORA       253-5246 9283  TROCHAIC TRAIL    SAN JOSE  |   |95131 

HY      KUVERSE    267-8961 650   LOTUS BLOSSOM WY  SAN JOSE  |   |95136 

CLARA   NETTE      243-4493 2667  GOODMAN DR        ALVISO    |   \95143 

EOF FOUND IN FROMFILE AFTER RECORD                            |    |

                                                              |    | 

12 RECORDS PROCESSED *** 0 ERRORS                             |    | 

                                                              |    | 

                             output in ascending order-------------|    | 

                           by key in byte location 67--------------------|

Use SUBSET= to list all the records with the characters "SUNNYVALE" starting in column 53; sequence is by alternate key in location 67:

 

  >FROM=JNAMES;TO=;KEY=67;SUBSET="SUNNYVALE",53 



  JEANNE    ALOGICAL  226-0295 4942  COUSIN CT     SUNNYVALE   95054 

  MIKE      ROMETER   269-1712 1681  MACHINIST DR  SUNNYVALE   95112 

  EOF FOUND IN FROMFILE AFTER RECORD 11 



   2 RECORDS PROCESSED *** 0 ERRORS

Another example using SUBSET= lists five records starting with the fourth record; sequence is by alternate key in location 67:

 

                               records numbered from 0 

                               | 

                               | 

                               ↓ 

>FROM=JNAMES;TO=;KEY=67;SUBSET=3,5 

ANNA    LOGUE       224-9934 1707   INVERSE WY     MOUNTAIN VIEW  95051 

JEANNE  ALOGICAL    226-0295 4942   COUSIN CT      SUNNYVALE      95054 

RHEA    PREYSELLE   365-8551 10789  REVIEW ROAD    SAN JOSE       95070 

ANNE    HOWE        372-4328 6547   EXUBERANCE WY  CAMPBELL       95112 

MIKE    ROMETER     269-1712 1681   MACHINIST DR   SUNNYVALE       95112 

5 RECORDS PROCESSED *** 0 ERRORS

If KEY=O, the file is copied in chronological order:

 

>FROM=JNAMES; TO=; KEY=0 

ARTHUR   MOMITER   443-5346 1554   MERCURY ST        MILPITAS      94173 

TRUDY   TEKTIFF    255-1005 17155  POIROT PL         CAMPBELL      95121 

ANNA    LOGUE      224-8934 1707   INVERSE WY        MOUNTAIN VIEW 95051 

CLARA   NETTE      243-4493 2667   GOODMAN DR        ALVISO        95143 

ANNE    HOWE       372-4328 6547   EXUBERANCE WY     CAMPBELL      95112 

JEANNE  ALOGICAL   226-0295 4942   COUSIN CT         SUNNYVALE     95054 

HY      KUVERSE    267-8961 650    LOTUS BLOSSOM WY  SAN JOSE      95136 

MIKE    ROMETER    269-1712 1681   MACHINIST DR      SUNNYVALE     95112 

ANNA    FORA       253-5246 9283   TROCHAIC TRAIL    SAN JOSE      95131 

POLLY   CHROMATIC  267-1413 1148   COLORFUL CT       SAN JOSE      95130 

RHEA    PREYSELLE  365-9551 10879  REVIEW ROAD       SAN JOSE      95070 

KURT    REMARQUE   243-1043 34     BRIEF ST          MILPITAS      94262 

EOF FOUND IN FROMFILE AFTER RECORD 11 



12 RECORDS PROCESSED *** 0 ERRORS