DEFINE FILE

Defines the attributes and characteristics of a file used by Enterprise Server.
Keyword Description
File(name) Names the file. Mandatory. name can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #.
Group(groupname) Names the group the file belongs to. Mandatory. groupname can be up to eight characters in length. Acceptable characters are A through Z, 0 through 9, $, @ and #. Do not specify a group name starting with DFH, as Mainframe Subsystem Support (MSS) uses that prefix for system groups.
Description(text) Describes the file. Optional. text can be up to 60 characters in length, with no restrictions except that if you use a left parenthesis you must ensure that there is a matching right parenthesis.
VSAM  
DSName(name) Specifies the name of the physical file. This is a mainframe-style data set name of up to 44 characters.
Remote  
REMOTESystem(name) Applicable only for remote files. Specifies the ID of the remote system that holds the file. This must correspond to either:
  • The Local SYSID field in the SIT used to run the related remote CICS region
  • The APPLID of another CICS system
REMOTEName(name) Applicable only for remote files. Names the remote file. Necessary only if it differs from the local file name.
RECORDSize(number) Applicable only for remote files. Specifies the maximum length in bytes of records in a remote file, in the range 1 through 32767.
Keylength(number) Applicable only for remote files. Specifies the length in bytes of the key for a remote file, in the range 1 through 32767.
Initial Status  
STAtus(Enabled|Disabled|Unenabled) Effective only for files owned by the local region. Specifies whether this file is accessible to transactions when the region is started.

Enabled: accessible at region startup

Disabled: not accessible at region startup

Unenabled: can be opened only by a SET FILE OPEN command. You cannot specify Unenabled for files of type Altindex

Opentime(Firstref|Startup) Indicates when the file is opened.

Firstref: the first time the file is referenced in the program being executed

Startup: when the region starts up

Note that this keyword controls only when the file is opened, not whether or not it is accessible; accessibility is controlled by the STAtus keyword.

Operations  
Add(No|Yes) Indicates whether users can add records to the file.
Browse(No|Yes) Indicates whether users can browse the file.
DELete(No|Yes) Indicates whether users can delete records from the file.
REAd(Yes|No Indicates whether users can read records in the file.
Update(No|Yes) Indicates whether users can update records in the file.
Recovery Parameters  
RECOVery(None|Backoutonly|All) Specifies the recovery options for this file:

None: the file is not recoverable

Backoutonly; the file is a protected resource and changes can be backed out. You must also define the file as being held on a Fileshare server, as Fileshare is required for backward recovery.

All: the file is a protected resource and has both forward and backward recovery capability. For forward recovery journals are used to record changes to the file. You must also define the file as being held on a Fileshare server, as Fileshare is required for forward and backward recovery.

Security  
RESsecnum(keys) Specifies one or more indicators, each corresponding to one of the 24 resource keys for this file. A user has access to a particular resource only through a matching key as defined in his sign-on table entry. To toggle a key on you specify its number here. By default all keys are toggled off. You code the keys as a comma-separated list of individual numbers and ranges separated by hyphens. For example, to toggle the keys 1 to 5 and 10 on, code RESSECNUM(1-5,10).
Micro Focus Extensions  
_MAxreclen(number) Specifies the maximum logical record length of the file in bytes, in the range 1 through 32767. The value must be greater than or equal to the value of _Minreclen. Specify a value if _FILEType is one of the following: KSDS, RRDS, ESDS or the file is remote (you specified a value in Remotesystem(name)).
_MInreclen(number) Specifies the minimum logical record length of the file in bytes , in the range 1 through 32767. The value must be less than or equal to the value of _Maxreclen. Specify a value if _FILEType is one of the following: KSDS, RRDS or ESDS.
_KEYPosition(number)

The key position is the offset, relative to zero, of the key from the beginning of the data record, in the range 0 through 32767. When set to 0, the key begins in the first position of the record. Specify a value if _FILEType is one of the following: KSDS or Altindex.

_KEYLength(number) Specifies the length of the record key in bytes, in the range 1 through 32767. The value of the following expression must not exceed the minimum record length:

key position + key length - 1

_FILEType(type) Specifies what type of file this is:

KSDS: key sequenced data set

ESDS; entry sequence data set

RRDS: relative record data set

Altindex: Alternate index for a KSDS file.

May be omitted if the file is defined as remote (you specified a value in Remotesystem(name)).

_Basefile(fileid) For a file of type Altindex, specifies the base data file for which this is an alternate index. fileid must correspond to the file name of another file definition of type KSDS.
_Startempty(No|Yes) Indicates whether the current contents of the file are deleted when the region starts up:

No: the file contents are not deleted

Yes: the file contents are deleted

_Dupkey(No|Yes) For an alternate index, indicates whether duplicate keys are allowed
_Path(string) Specifies the path of the physical file if you want to override the default path. Do not include the filename or the file extension. Mandatory if the file is held on a Fileshare server, in which case _FILEShareid must be present too.
_FILEShareid(name) Specifies the Fileshare server on which the file resides. name can be up to 16 characters in length.
_FILEFormat(Microfocus|IDXFMT4|IDXFMT8|IDXFMT9) Specifies the format for files that are to be created by Mainframe Transaction Option. We recommend that you use the default, IDXFMT8.
_FILEName(name) Specifies the name of the physical PC file if you want to override the default filename, which is the name given by File(name). Do not include the file extension.
_FILEExt(value) Specifies the file extension of the physical file if you want to override the default, which is .dat
_Collseq(Ebcdic|Ascii) Specifies the collating sequence used in the file.

Example

DEFINE FILE(SAMPLEA) GROUP(SAMPGRP)
DESCRIPTION(Sample KSDS FCT entry)
       STATUS(ENABLED) OPENTIME(STARTUP) RECORDFORMAT(F) ADD(YES)
       BROWSE(YES) DELETE(YES) READ(YES) UPDATE(YES)
       RECOVERY(BACKOUTONLY) _FILETYPE(KSDS) _MAXRECLEN(200)
       _MINRECLEN(200) _KEYPOSITION(1) _KEYLENGTH(6) _STARTEMPTY(YES)
       _DUPKEY(NO) _FILEEXT(DAT) _FILEFORMAT(MICROFOCUS)
DEFINE FILE(SAMPLEA1) GROUP(SAMPGRP)
DESCRIPTION(Index for SAMPLEA)
       STATUS(ENABLED) OPENTIME(FIRSTREF) RECORDFORMAT(F) ADD(YES)
       BROWSE(YES) DELETE(YES) READ(YES) UPDATE(YES)
       RECOVERY(BACKOUTONLY) _FILETYPE(ALTINDEX) _BASEFILE(SAMPLEA)
       _KEYPOSITION(8) _KEYLENGTH(4) _STARTEMPTY(NO) _DUPKEY(NO)
       _FILEEXT(DAT) _FILEFORMAT(MICROFOCUS)
DEFINE FILE(SAMPLEB) GROUP(SAMPGRP)
DESCRIPTION(Sample RRDS entry)
       STATUS(ENABLED) OPENTIME(FIRSTREF) RECORDFORMAT(F) ADD(YES)
       BROWSE(YES) DELETE(YES) READ(YES) UPDATE(YES)
       RECOVERY(BACKOUTONLY) _FILETYPE(RRDS) _MAXRECLEN(500)
       _MINRECLEN(500) _STARTEMPTY(NO) _DUPKEY(NO) _PATH(x:\cics\fshr)
       _FILESHAREID(FSHRCIC2) _FILEEXT(DAT) _FILEFORMAT(MICROFOCUS)
       RESSECNUM(01-08,17-22,24)
DEFINE FILE(SAMPLEC) GROUP(SAMPGRP)
DESCRIPTION(Example of an ESDS)
       STATUS(ENABLED) OPENTIME(FIRSTREF) RECORDFORMAT(F) ADD(YES)
       BROWSE(YES) DELETE(NO) READ(YES) UPDATE(NO)
       RECOVERY(BACKOUTONLY) _FILETYPE(ESDS) _MAXRECLEN(1000)
       _MINRECLEN(120) _STARTEMPTY(NO) _DUPKEY(NO) _FILEEXT(DAT)
       _FILEFORMAT(MICROFOCUS) _FILENAME(TESTC) _USECATALOG(NO)