The FILE statement supplies the system with information about disk files. The system uses this information to read records from and write records on disk.
You must supply a FILE statement for each of the new disk files that your programs create, and for each of the existing disk files that your programs use. The maximum number of f iles allowed is explained under Schedu ler Work Area in Part 2 of this manual.
The FILE statement must follow the LOAD or CALL statement and precede the RUN statement.
// FILE parameters
All of the parameters are keyword parameters. as follows (keywords are in capital letters):
N A M E - f i l e n a m e ( i n p r o g r a m )
UNIT-5444 unit code or main data area code P A C K - n a m e
L A B E L - f i l e n a m e ( o n d i s k )
R ECO R DS-number or TRACKS-number /
I t r a c k n u m b e r ( s i m u l a t i o n a r e a o n l y ]
I
L O C A T I O N -
{ c v l i n d e r n u m b e r \
! tvtain data area only f c y l i n d e r n u m b e r / t r a c k n u m b e r t
\ R E T A I N - c o d e DATE-date V E R I F Y - c o d e S H A R E - c o d e
T h e N A M E , P A C K , a n d U N I T p a r a m e t e r s a r e a l w a y s r e q u i r e d . T h e o t h e r s a r e re q u i r e d o n l y u n d e r c e r t a i n c o n d i t i o n s .
NAME: The NAME parameter is always needed. lt tells the system the name that your program uses to refer to the file. The NAME parameter must be placed on the first record or line if two or more records or lines are used for the FILE statement. (See General Coding Rules f or rules on continuation.)
F I L E S t a t e m e n t ( S i n g l e V o l u m e D i s k F i l e s l 1 - 2 9
Page of GC21-5162-1
,,',n" t"r name can be repraced by the name specified on a contror statement paramerer.
r T y o u s u p p r y a LABEL parameter in the FrLE starement, ir must be LABEL-$rNDEX4o.
1-30
Program
Macro Processor O v e r l a y L i n k a g e E d i t o r
Spool (See Note) Any program adding to large i n d e x e d f i l e s o r l o a d i n g a l a r g e unordered i n d e x e d f i l e .
F i l e Output I n p u t W o r k Work Work
Name
$ S O U R C E
$ S O U R C E O p t i o n a l - either both
$WORK present or both absent
$SPOOL
$ l N D E X 4 5 1 ( O p t i o n a l ) ( f o r m a i n d a t a a r e a f i l e ) or
$ l N D E X 4 O 2 ( O p t i o n a l ) ( f o r m a i n d a t a a r e a f i l e )
lUote.' The $SPOOL file is internally generated by spooling and cannot be referenced on a F I L E s t a t e m e n t .
The keyword, NAME, must be followed by the filename used by the program. The file-name can be any combination of characters except commas, apostrophes, or blanks. The first character must be alphabetic. The number of characters must not exceed 8. The f o l l o w i n g e x a m p l e s h o w s h o w t h e N A M E p a r a m e t e r f o r a f i l e n a m e d F I L E A w o u l d b e c o d e d :
IJNIT: The UNIT parameter is always needed. lt tells the system the simulation area or m a i n d a t a a r e a t h a t c o n t a i n s o r w i l l c o n t a i n t h e f i l e . T h e k e y w o r d , U N I T . m u s t b e f o l f o w e d b y a c o d e t h a t in d i c a t e s t h e a r e a . P o s s i b l e c o d e s a r e R 1 , F 1 , R 2 , F 2 , D 1 , D 2 , D 3 o r D 3 1 . D 3 2 , D 3 3 , D 3 4 , D 4 o r D 4 1 , D 4 2 , D 4 3 , D 4 4 .
The previous example shows how the UNIT parameter for a file located on the main data area D1 would be coded.
PACK: The PACK parameter is always needed. lt tells the system the name of the area that contains or will contain the file. The system checks this name to ensure that the proper area is being used. (For information about how an area is given a name. see Disk lnitialization Program or Simulation Area Program in Part 4 of this manual.)
The keyword, PACK, must be followed by the name of the area. The example under N A M E s h o w s h o w t h e P A C K p a r a m e t e r f o r a f i l e o n a n a r e a n a m e d V O L I w o u l d b e coded.
1 l f y o u supply a LABEL parameter in the FILE statement, it must be LABEL-$lNDEX45.
' l f you supply a LABEL parameter in the FILE statement, it must be LABEL-$l NDEX40.
F I L E S t a t e m e n t ( S i n g l e V o l u m e D i s k F i l e s ) 1 - 3 1
L A B E L : T h e L A B E L p a r a m e t e r t e l l s t h e s y s t e m t h e n a m e b y w h i c h y o u r f i l e i s id e n t i f i e d o r w i l l b e id e n t i f i e d .
l f t h e f i l e i s b e i n g c r e a t e d , t h e n a m e y o u s u p p l y i n t h e L A B E L p a r a m e t e r i s u s e d t o i d e n t i f y t h e f i l e . l f y o u o m i t t h e L A B E L p a r a m e t e r f r o m a d i s k F I L E s t a t e m e n t . t h e n a m e f r o m t h e N A M E p a r a m e t e r i s u s e d .
W h e n t h e n a m e y o u r p r o g r a m u s e s t o r e f e r t o a n e x i s t i n g d i s k fi l e d i f f e r s f r o m t h e n a m e b y w h i c h th e f i l e i s id e n t i f i e d , y o u m u s t s u p p l y a L A B E L p a r a m e t e r .
The keyword, LABEL, must be followed by the name of the file. The name can be any combination of characters except commas, apostrophes, or blanks. The first character must be alphabetic. The number of characters must not exceed 8. The LABEL param-e t param-e r fo r a f i l param-e n a m param-e d P A Y R O L L is c o d e d i n t h e f o l l o w i n g e x a m p l e :
TRACKS or RECOBDS: The TRACKS or RECORDS parameter is needed for f iles that are being created. The parameter tells the system the amount of space needed on disk for t h e f i l e .
l f y o u u s e t h e T R A C K S k e y w o r d , y o u s p e c i f y t h e n u m b e r o f d i s k tr a c k s n e e d e d f o r t h e f il e .
lf you use the RECORDS keyword, you specify the approximate number of records for t h e f i l e . T h e to t a l s p a c e a l l o c a t e d w i l l b e r o u n d e d u p t o f u l l t r a c k s , a l l o w i n g a d e q u a t e space to accommodate at least the number of records indicated. This means the file could h o l d m o r e re c o r d s t h a n s p e c i f i e d o n t h e R E C O R D S k e y w o r d . a l l o w i n g y o u t o a d d m o r e records to the file. Therefore, when using the copy/dump program ($COPY) to copy the file to another disk. you may have to specify more records than were specified in the RECORDS keyword when the file was created.
E i t h e r T R A C K S o r R E C O R D S c a n a p p e a r i n t h e F I L E s t a t e m e n t , b u t n o t b o t h . T h e keyword must be followed by a number indicating the amount of space needed.
W h e n l o a d i n g a n e w fi l e a t t h e s a m e l o c a t i o n a s a n e x i s t i n g f i l e , u s i n g t h e L O C A T I O N parameter, you must specify the same parameter (TRACKS or RECORDS) that was used w h e n th e e x i s t i n g f i l e w a s c r e a t e d . ( T h e e x i s t i n g f i l e m u s t b e a t e m p o r a r y f i l e . )
Several versions of a file can be created on the same disk and be given the same name. lf t h e T R A C K S o r R E C O R D S p a r a m e t e r y o u a r e u s i n g i n c r e a t i n g a f i l e i s th e s a m e a s th e T R A C K S o r R E C O R D S s p e c i f i e d f o r a n e x i s t i n g f i l e , y o u m u s t s p e c i f y L O C A T I O N . Y o u can reference each of these files by its name and date, or by its name and location on disk. Both date and location must be unique for each version. (See Example 2, Example 4, and File Processing Considerations.l
1-32
l f T R A C K S i s u s e d , t h e n u m b e r m u s t b e w i t h i n th e r a n g e o f 1 - 3 9 8 f o r a s i m u l a t i o n a r e a ; 1-3320for a main data area on a 3340, and 1-3720 for a main data area on a 3344. The f o l l o w i n g e x a m p l e s h o w s h o w t h e T R A C K S p a r a m e t e r f o r a f il e r e q u i r i n g 2 0 t r a c k s i s coded:
l f R E c o R D S is u s e d , t h e n u m b e r c a n b e u p t o s i x d i g i t s l o n g . T h e R E c o R D S p a r a m e t e r f o r a f i l e c o n t a i n i n g 2 5 0 r e c o r d s i s c o d e d a s fo l l o w s :
L O C A T I O N : L O C A T I O N i s r e q u i r e d w h e n y o u c r e a t e a f i l e w i t h t h e s a m e L A B E L ( t h e d a t e m u s t b e u n i q u e ) a n d th e s a m e s i z e a s o n e th a t a l r e a d y e x i s t s ( L O C A T I O N i s n o t r e q u i r e d i f s i z e s d i f f e r ) , l o a d t o a n e x i s t i n g f i l e , a n d lo a d a n o f f l i n e m u l t i v o l u m e f i l e t o v o l u m e s t h a t c o n t a i n o t h e r fi l e s .
The LOCATI ON parameter can be used to specify the first track of a new file. lt may a l s o b e u s e d w h e n a f il e is r e f e r e n c e d , f o r a m o r e s p e c i f i c i d e n t i f i c a t i o n c h e c k , a n d fo r i d e n t i f y i n g o n e o f s e v e r a l f i l e s h a v i n g t h e s a m e n a m e a n d s a m e s i z e .
l f y o u a r e c r e a t i n g a f i l e . th i s p a r a m e t e r t e l l s t h e s y s t e m t h e n u m b e r o f t h e t r a c k o n w h i c h t h e f i l e i s to b e g i n . lf y o u o m i t t h e p a r a m e t e r . t h e t r a c k is c h o s e n f o r y o u . T h e s y s t e m p l a c e s t h e f i l e i n t h e s m a l l e s t a v a i l a b l e s p a c e o n t h e p a c k , l e a v i n g a s fe w e m p t y s p a c e s a s p o s s i b l e .
lf you are referencing a file, the parameter tells the system the number of the track on w h i c h th e f i l e b e g i n s . I n t h i s c a s e , t h e s y s t e m u s e s t h e t r a c k n u m b e r t o d i s t i n g u i s h o n e f i l e f r o m a n o t h e r .
F o r a s i m u l a t i o n a r e a , t h e L O C A T I O N f o r m a t is : L O C A T I O N - t r a c k n u m b e r
Track number must be between 8 and 405.
Tracks 0-7 are reserved for the svstem.
F o r a m a i n d a t a a r e a , t h e L O C A T I O N f o r m a t is :
t
Tralk number must be between 0 and 19. Track n u m b e r 0 i s a s s u m e d i f t r a c k n u m b e r i s n o t s p e c i f i e d . C y l i n d e r n u m b e r m u s t b e b e t w e e n 1 a n d 1 6 6 ( m a i n
data area on 3340) or 1 and 186 (main data area on a 3344). Cylinder 0 is reserved for the system.
F I L E S t a t e m e n t ( S i n g l e V o l u m e D i s k F i l e s ) 1 - 3 3
R E T A I N : T h e R E T A I N keyword must be followed c a t i o n s o f t h e f i l e . T h e c o o e s a r e :
b y a c o d e t h a t i n d i c a t e s t h e c l a s s i f i
-Codr:
S T P
Meaning Scratch file T e m p o r a r y fi l e P e r m a n e n t f i l e
A scratch file is used only once in a program and cannot be retrieved after the program h a s e n d e d . T o r e m o v e a p e r m a n e n t file you must use the file delete (gDELET) system s e r v i c e p r o g r a m . Y o u c a n r e m o v e a temporary fire by using the fire derete (gDELET) s y s t e m s ; e r v i c e p r o g r a m o r b y u s i n g a RETAIN-s parameter. A temporary file can be c h a n g e d t o a p e r m a n e n t f i l e o n l y i f t h e f i l e n a m e i s c h a n g e d or copied as a permanent f i l e .
A t e m p o r a r y f i l e i s u s u a l l y u s e d m o r e than once. The area containing a temporary file c a n b e g i v e n to a n o t h e r fi r e onry under one of the foilowing conditions:
' A F l l - E statement containing the RETAIN-S parameter is supplied for the temporary f i l e a n d t h e f i l e r e f e r e n c e d ( o p e n e d a n d c l o s e d ) b y t h e u s e r p r o g r a m . T h i s statement r e m o ' / e s t h e f i l e f r o m t h e V T o c ( v o l u m e ta b l e of contents) when the program with t h e F I L E s t a t e m e n t g o e s to e n d o f j o b . T h e u s e r must be aware of any external i n d i c a t o r s t h a t c o n d i t i o n t h e u s e o f t h a t f i l e . M o r e information about deleting files is provided under General Results When the 2 or 3 Option for a Message is Selected in the IBM System/3 Modet lS System Mesages, GC21-5076.
o A n o t h e r f i l e with the same LABEL name is loaded into the exact area occupied by t h e t e m p o r a r y f i l e , b u t t h i s o n l y changes t h e d a t a . s p a c e a n d l o c a t i o n p a r a m e t e r s a r e r e q u i r e d . Y o u m u s t s p e c i f y the same parameter (TRACKS or RECoRDS) that w a s u s e d w h e n t h e e x i s t i n g fi l e w a s created. For example, if the TRACKS parameter w a s s p e c i f i e d w h e n t h e F I L E w a s c r e a t e d , y o u m u s t u s e th e T R A C K S p a r a m e t e r w h e n r e l o a d i n g t h e s a m e lo c a t i o n o n t h e p a c k .
o T h e f i l e d e l e t e p r o g r a m is used to delete the f ile.
T h e a r e a c o n t a i n i n g a p e r m a n e n t fi l e cannot be used for any other file until the file d e l e t e p r o g r a m h a s d e l e t e d th e p e r m a n e n t f ile.
A d i s k f i t e i s c l a s s i f i e d a s s c r a t c h , t e m p o r a r y , o r p e r m a n e n t w h e n i t i s c r e a t e d . lf the R E T A I N p a r a m e t e r i s o m i t t e d f r o m t h e F I L E s t a t e m e n t when the file is created, the file i s a s s u m e d t o b e a t e m p o r a r y f i l e . Y o u m a y o m i t the RETAIN parameter when accessino a n e x i s t i r r g f i l e .
1 - 3 4
Notes:
1 . T h e o u t p u t f i l e w i l l b e s c r a t c h e d ( d e l e t e d ) i f a l l th r e e o f t h e f o l l o 6 n g c o n d i t i o n s exist at end of job step:
a . A p a c k c o n t a i n i n g a n in p u t fi l e i s n o t o n l i n e at the start of the iob ( d e f e r r e d m o u n t ) .
b. The output fire is to be written over the input fire (road to ord).
c . R E T A I N - S i s u s e d o n t h e F I L E s t a t e m e n t f o r t h e in p u t f i l e .
To prevent the deletion of the output fire, you shourd use RETATN-T for the input file.
2 ' Y o u s h o u l d r e l o a d a n e x i s t i n g t e m p o r a r y f i l e ( l o a d t o o l d ) w i t h f i l e s o f l i k e attributes.
l f a n e x i s t i n g i n d e x e d f i l e i s r e l o a d e d w i t h a s e q u e n t i a l f i l e , th e n e w d a t a w i l l overlay only the data portion of the indexed file. The index portion of the file will remain i n t a c t b u t w i l l n o t be usable.
DATE: The DATE parameter teils the system the creation date of an input fire. rt is used to ensure that the proper version of the file is used. The date specified is compared with the creation date contained in the file label. No comparison is done when DATE is not specified.
For output files, the partition date is always used as the creation date. rf the DATE parameter is specified for an output file, the system compares the specified date with the creation date of the existing file. lf no file exists, or if the dates do not agree, the system halts' (See lnterval Timer for information on the effect of the interval timer on date.) The date may be coded in one of two formats: month_day-year (mmddyy), or day-month-year (ddmmyy). The format must match the format of the system date chosen during system generation. The date may be coded with or without punctuation.
Blanks, commas, numbers, or apostrophes are not ailowed as punctuation. Leading zeros in month and day may be omitted if punctuation is used.
To illustrate this parameter, assume that two versions of a file are written on the same m a i n d a t a a r e a . In the next example a r e th e N A M E , L A B E L, and DATE parameters f o r two versions of a file on the same main data area, one written on April s, 1976,the other o n A u g u s t 3 , 1 9 7 6 . B o t h fi l e s h a v e t h e s a m e l a b e l : F 0 0 0 1 .
The R ETAIN parameter for a permanent f ile is coded as follows:
F I L E S t a t e m e n t (S i n g t e V o l u m e D i s k F i t e s ) 1 _ 3 5
E x a m p l e s
VERIFY': The VERIFY parameter is used to specify verification of disk write operations f o r t h i s f i l e i n t h i s s t e p ( m a i n d a t a a r e a o n l y ) . l f V E R I F Y - Y E s i s s p e c i f i e d , v e r i f i c a t i o n t a k e s p l a c e . lf V E R I F Y - N O i s s p e c i f i e d , w r i t e v e r i f i c a t i o n i s b y p a s s e d . l f V E R I F Y i s n o t s p e c i f i e d , V E R I F Y - Y E S i s a s s u m e d u n l e s s R E T A I N - S i s c o d e d , i n w h i c h c a s e V E R I F Y - N O i s a s s u m e d . V e r i f i c a t i o n i s a l w a y s d o n e w h e n a s i m u l a t i o n a r e a i s a c c e s s e d .
SHARE: The SHARE parameter is used to allow or disallow file sharing between parti-t i o n s i f parti-t h e a c c e s s m e parti-t h o d s a r e c o m p a parti-t i b l e . I f S H A R E - Y E S i s s p e c i f i e d , f i l e s h a r i n g i s a l l o w e d b e t w e e n p a r t i t i o n s ( o f f l i n e m u l t i v o l u m e f i l e s c a n n o t b e s h a r e d ) ; S H A R E - N O d o e s n o t a l l o w f i l e s h a r i n g b e t w e e n p a r t i t i o n s . l f R E T A I N - S i s s p e c i f i e d o n t h e F l L E s t a t e m e n t , f i l e s h a r i n g i s n o t a l l o w e d . lf t h i s p a r a m e t e r i s o m i t t e d , S H A R E - Y E S i s assumed. For additional information about f ile sharing, refer to File Sharing in Part 2 o f t h i s m a n u a l .
T h e fo l l o w i n g a r e e x a m p l e s o f F I L E s t a t e m e n t s . I n e a c h e x a m p l e , t h e f i l e i s d e s c r i b e d first, therr the corresponding FILE statement is shown.
Example /.' Suppose that each week you create a disk f ile that contains the records for the transactions you had made that week. Assume the following facts about that file:
. The name your program uses to refer to the file is TRANS. which is also the name you w a n t to u s e t o i d e n t i f y t h e f i l e o n d i s k .
Y o u a r e p l a c i n g t h e f i l e i n a m a i n d a t a a r e a n a m e d V O L 0 3 . You irrtend to mount the data module on drive 2.
You want to save the file for use at the end of the month.
The file contains 225 records.
You are letting the system choose the area that will contain the file.
T h e fo l l o w i n g e x a m p l e s h o w s h o w t h e F I L E s t a t e m e n t f o r t h e p r e c e d i n g f i l e i s c o d e d :
1 - 3 6
Example 2.' suppose you had created, on the same data module (voLo3), four versions of the transaction file described in the preceding example-one for each of the weeks in F e b r u a r y 1 9 7 6 . A s s u m e t h e f o l l o w i n g :
o Y o u had created t h e f i l e s o n t h e f o l l o w i n g d a y s : 2 1 6 / 7 6 , 2 1 1 3 1 7 6 , 2 / 2 0 / 7 6 . a n d 2127 176 (these were the system dates used for each of the files).
o You want to reference the third file (the one created 2120176l . r Y o u i n t e n d to mount the data module o n d r i v e 2 .
T h e F I L E s t a t e m e n t y o u w o u l d n e e d is:
Example 3.' Suppose that at the end of the month you combine the files referred to in e x a m p l e 2 , f o r u s e in p r e p a r i n g y o u r m o n t h l y b i l l s . F u r t h e r a s s u m e t h e fo l l o w i n g : o Your program uses the name TRANS to refer to the file, but you want to use the name
B I L L I N G to i d e n t i f y t h e f i l e o n d i s k .
o You are expressing the amount of disk space as the number of tracks required to con-t a i n con-th e f i l e ( a s s u m e t h e n u m b e r i s 1 5 ) , a n d y o u w a n t th e f i l e t o b e g i n o n c y l i n d e r 8 , track 0.
o Y o u are placing t h e f i l e in a m a i n d a t a a r e a n a m e d V O L 0 3 . o You intend to mount the data module on drive 2.
T h e fo l l o w i n g e x a m p l e s h o w s t h e F I L E s t a t e m e n t y o u w o u l d u s e fo r this file.
F f L E S t a t e m e n t ( S i n g l e V o l u m e D i s k F i l e s ) 1 - 3 7
Example 4" Suppose you want to create two versions of two files on disk and later to access one version of each f ile. Further assume the following:
o The names your program uses to refer to the files are AA and BB, which are also the names you want to use to identify the files on disk.
o Files AA and BB are being praced on a data modure on drive 2 named D2D2D2.
o O n e version o f e a c h f i l e is c r e a t e d o n 1 1 1 2 / 7 6 a n d 1 / 1 3 1 7 6 . o Disk space and location for the files are:
File Version A A 1 1 1 2 / 7 6
1 / 1 3 1 7 6
Tracks Location
B B 1 / 1 2 / 7 6 1 / 1 3 / 7 6
120/O 130/0 140/O 1 50/0 1 0
1 0 20 20
o Y o u want to access f i r e A A , v e r s i o n 1 / 1 2 / 7 6 , a n d f i r e B B , v e r s i o n 1 1 1 3 / 7 6 .
The following OCL statements are needed to create the above versions of files AA and BB and to access a version of each file.
1-38
F i l e P r o c e s s i n g C o n s i d e r a t i o n s L O C A T I O N a n d s p a c e ( T R A C K S o r R E C O R D S ) m u s t b e s p e c i f i e d w h e n y o u a r e re l o a d . i n g a n e x i s t i n g t e m p o r a r y f i l e . Y o u m u s t s p e c i f y t h e s a m e p a r a m e t e r ( T R A C K S o r R E C O R D S ) t h a t y o u u s e d w h e n th e e x i s t i n g f i l e w a s c r e a t e d .
lf you are referencing a file by the DATE parameter and space is given, the space must be equal to the space given when that file was created.
lf you are accessing a file by the LOCATION parameter and space is given, the space must be equal to the space given when that file was created.
You can create several versions of a file with a program by changing the locations of the f i l e s a n d u s i n g d i f f e r e n t p a r t i t i o n d a t e s .
You can create different versions of a file without LOCATION if the space parameters as well as the partition dates are different.
T h e D A T E p a r a m e t e r i s a l l o w e d o n l y f o r a c c e s s i n g e x i s t i n g f i l e s .
Whenever a load is performed to an existing file (load to oldl, the partition date replaces the previous date for that f ile.
T h e o n l y f i l e t h a t c a n b e r e l o a d e d i s a f i l e th a t h a s a R E T A I N - T c l a s s i f i c a t i o n . When a scratch file is created, it is not entered in the volume table of contents (VTOC).
After the job step that created the file is executed, the file cannot be accessed.
Spooling Considerations None
F I L E S t a t e m e n t ( S i n g l e V o l u m e D i s k F i l e s ) 1 - 3 9