isCOBOL Evolve : Appendices : Library Routines : I$IO : MAKE-FUNCTION
MAKE-FUNCTION
This function is used to create a new indexed file. If the file already exists, it will be overwritten.
Syntax
 SET MAKE-FUNCTION TO TRUE
 
 CALL "I$IO" USING IO-FUNCTION
                   name
                   comment 
                   pParms
                   lParms
                   keys
                   trans
            GIVING returnCode
Parameters:
name
points to the name of the file.
comment
may be NULL or may point to comment string that describes the file.
pParms
points to a string that describes various physical characteristics of the file.
 
A structure called PHYSICAL-INFO is provided in the "isfilesys.def" copybook.
 
These fields should be set to zero
lParms
points to a string that describes various logical characteristics of the file
 
The "isfilesys.def" copy file has a data item containing these fields:
• Maximum record size, the size of the largest record to be placed in the file.
• Minimum record size, the size of the smallest record to be placed in the file.
• Number of keys, the number of keys in the file, including the primary key.
keys
points to a null-terminated string that describes the key structure for the file.
 
keys is a string of numbers separated by commas.
 
The first key described is the primary key. It may not allow duplicate values. The primary key is called key "0".
 
The next key described is key "1" and so on. There should be as many keys described as the "number of keys" field of l_parms indicates.
 
The "isfilesys.def" copy file has a data item containing these fields for each key:
• Number of segments, the number of segments in this key.
• Duplicates flag. If this value is "1", then duplicate keys are allowed. If "0", then duplicate values are not allowed.
• Segment size, the number of bytes in the first segment.
• Segment offset, the offset from the beginning of the record to the first byte of the segment.
• Remaining segments. The segment size and segment offset fields are repeated for each additional segment in the key.
 
For example, a file with two keys, the first one having two segments (offset zero, length 10 and offset 50, length 5) and the second one with one segment (offset 20, length 15) and allowing duplicates would be written:
 
2,0,10,0,5,50,1,1,15,20
trans
This parameter specifies an alternate collating sequence for the keys.
 
If this parameter is NULL or omitted, then keys are ordered in ascending sequence based on their native unsigned value.
Be aware that compiling with -ca option causes NULL to be translated to 0, that is an invalid collating sequence, therefore omitting the parameter is safer than setting it to NULL.
 
If it is not NULL, it must point to a 256 byte region of memory.
 
Unlike other strings, this need not be null-terminated and is likely to contain nulls within it. This 256 byte region is used as a translation table on the bytes of each key to arrive at a new key-ordering. Each byte is used as an index into this table, and the resulting value is used to order the keys.
Return code:
returnCode can be any signed numeric data item and provides additional information:
>0
Operation successful.
0
Operation failed.