Example: accessing SFS files

The following example shows COBOL file descriptions that you might code and sfsadmin and export commands that you might issue to create and access two SFS files.

SFS04 is an indexed file that has no alternate index. SFS04A is an indexed file that has one alternate index, SFS04A1.

COBOL file descriptions

. . .
Environment division.
Input-output section.
File-control.
    select SFS04-file
        assign to SFS04EV
        access dynamic
        organization is indexed
        record key is SFS04-rec-num
        file status is SFS04-status.
        
    select SFS04A-file
        assign to SFS04AEV
        access dynamic
        organization is indexed
        record key is SFS04A-rec-num
        alternate record key is SFS04A-date-time
        file status is SFS04A-status.
        
Data division.
File section.
FD  SFS04-file.
  01 SFS04-record.
     05 SFS04-rec-num               pic x(10).
     05 SFS04-rec-data              pic x(70).     
FD  SFS04A-file.
  01 SFS04A-record.
     05 SFS04A-rec-num              pic x(10).
     05 SFS04A-date-time.
        07 SFS04A-date-yyyymmdd     pic 9(8).
        07 SFS04A-time-hhmmsshh     pic 9(8).
        07 SFS04A-date-time-counter pic 9(8).
     05 SFS04A-rec-data             pic x(1000).

sfsadmin commands

Create each indexed file by issuing the sfsadmin create clusteredfile command, and add an alternate index by issuing the sfsadmin add index command:

sfsadmin create clusteredfile SFS04 2 \
PrimaryKey byteArray 10 \
DATA byteArray 70 \
primaryIndex -unique 1 PrimaryKey sfsVolume
#
sfsadmin create clusteredfile SFS04A 3 \
PrimaryKey byteArray 10 \
AltKey1 byteArray 24 \
DATA byteArray 1000 \
primaryIndex -unique 1 PrimaryKey sfsVolume
#
sfsadmin add index SFS04A SFS04A1 1 AltKey1

As shown in the first sfsadmin create clusteredfile command above, you must specify the following items:

  • The name of the new indexed file (SFS04 in this example)
  • The number of fields per record (2)
  • The description of each field (PrimaryKey and DATA, each a byte array)
  • The name of the primary index (primaryIndex)
  • The -unique option
  • The number of fields in the primary index (1)
  • The names of the fields in the primary index (PrimaryKey)
  • The name of the data volume on which the file is to be stored (sfsVolume)

By default, Encina SFS allows duplicate keys in the primary index of a clustered file. However, you must specify the -unique option as shown above because COBOL requires that key values in the primary index be unique within the file.

As shown in the sfsadmin add index command above, you must specify the following items:

  • The name of the file to which an alternate index is to be added (SFS04A in this example)
  • The name of the new index (SFS04A1)
  • The number of fields to be used as keys in the new index (1)
  • The names of the fields in the new index (AltKey1)

For details about the syntax of the commands sfsadmin create clusteredfile and sfsadmin add index, see the related references.

export commands

Before you run the program that processes the SFS files, issue these export commands to specify the path (/.:/cics/sfs) to the Encina SFS server (sfsServer) that will access the files, and the data volume (sfsVolume) that will store the files:

# Set environment variables required by the SFS file system
# for SFS files:
export ENCINA_CDS_ROOT=/.:/cics/sfs/
export ENCINA_SFS_DATA_VOLUME=sfsVolume
export ENCINA_SFS_INDEX_VOLUME=sfsVolume 

# Set SFS as the default file system:
export COBRTOPT=FILESYS=SFS

# Enable use of a short-form SFS specification:
export CICS_TK_SFS_SERVER=/.:/cics/sfs/sfsServer

# Set the environment variable to access SFS file SFS04
# (an example of using a short-form SFS specification):
export SFS04EV=SFS04

# Set the environment variable to access SFS
# file SFS04A and the alternate index SFS04A1:
export SFS04AEV="/.:/cics/sfs/sfsServer/SFS04A(/.:/cics/sfs/sfsServer/SFS04A;SFS04A1)"