Index Facility - Revision history

Laura: /* Split Key */

2013-05-29T20:36:32Z

Split Key

← Older revision		Revision as of 20:36, 29 May 2013
Line 44:		Line 44:

	===Split Key===		===Split Key===
	~~When more than one section of a record is used to form the~~ key ~~field (up to six sections).~~		{{:Split key}}

	===BADKEYS===		===BADKEYS===

Laura: /* BADKEYS */

2013-05-29T20:35:39Z

BADKEYS

← Older revision		Revision as of 20:35, 29 May 2013
Line 47:		Line 47:

	===BADKEYS===		===BADKEYS===
	The INDEX command may now specify BADKEYS or LISTBADKEYS to effect the same processing as DUPKEYS and LISTDUPKEYS performs. If both LISTBADKEYS and LISTDUPKEYS are specified, then all bad keys are listed ahead of dupkeys. They can be distinguished by whether or not they are duplicate.		{{:Badkeys}}

	==BTree Facility==		==BTree Facility==

Laura: /* INDEX file */

2013-05-29T20:34:32Z

INDEX file

← Older revision		Revision as of 20:34, 29 May 2013
Line 21:		Line 21:

	===INDEX file===		===INDEX file===
	{{Index file}}		{{:Index file}}

	===Key field===		===Key field===

Laura: /* INDEX file */

2013-05-29T20:34:19Z

INDEX file

← Older revision		Revision as of 20:34, 29 May 2013
Line 21:		Line 21:

	===INDEX file===		===INDEX file===
	~~An index file is created when an~~ Index command is executed or (less frequently) when an OPEN internal statement creates a new master file. Also called a key file, the index file helps a program quickly access the information in a master file.		{{Index file}}

	~~An index file contains a key field and an address (or relative record number) for each record in the master~~ file~~, similar to the way in which a telephone directory contains the name and address of each resident in a city.~~

	===Key field===		===Key field===

Laura: /* Key file */

2013-05-29T20:33:36Z

Key file

← Older revision		Revision as of 20:33, 29 May 2013
Line 31:		Line 31:

	===Key file===		===Key file===
	~~Another name for an index~~ file.		{{:Key file}}

	===Master file===		===Master file===

Laura: /* Duplicate keys */

2013-05-29T20:31:26Z

Duplicate keys

← Older revision		Revision as of 20:31, 29 May 2013
Line 15:		Line 15:

	===Duplicate keys===		===Duplicate keys===
	A duplicate key is a key field that is exactly the same in two or more records in the master file. The Index command's DUPKEYS parameter allows you to choose whether or not to receive a warning message if duplicate keys ~~are found in the index file. Including duplicate keys does not cause duplicate entries in the index file, as the relative numbers for each entry are different.~~		{{:Duplicate keys}}

	With or without the warning message, the Index command always creates an index file which always includes the duplicate keys. The Index command's LISTDUPKEYS parameter can be used to list all duplicate keys. This optional listing is sent to the screen by default, but can also be sent to a printer or display file.

	===Index command===		===Index command===

Laura: /* Baseyear dependent indexes */

2013-04-08T19:25:41Z

Baseyear dependent indexes

← Older revision		Revision as of 19:25, 8 April 2013
Line 164:		Line 164:
	\|}		\|}

	Note that the specification for PD is P and the specification for BH is B in the INDEX statement.		Note that the specification for PD is P and the specification for BH is B in the INDEX statement, for example:

	~~e.g.~~ INDEX masterfile keyfile 10/31 2BY/10 REPLACE		INDEX masterfile keyfile 10/31 2BY/10 REPLACE

	This creates 'keyfile' applying BASEYEAR to the first two digits of each key. In this example, the first part of the key is assumed to be binary in YYMM format.		This creates 'keyfile' applying BASEYEAR to the first two digits of each key. In this example, the first part of the key is assumed to be binary in YYMM format.

Laura: /* Techniques for using multiple index files */

2013-04-08T19:24:31Z

Techniques for using multiple index files

← Older revision		Revision as of 19:24, 8 April 2013
Line 65:		Line 65:
	The use of multiple index files allows processing records in a master file by different key fields, such as customer number, last name, zip code, date, etc. If it is not possible or convenient to locate a record by one key, the same program can try to retrieve it by another key.		The use of multiple index files allows processing records in a master file by different key fields, such as customer number, last name, zip code, date, etc. If it is not possible or convenient to locate a record by one key, the same program can try to retrieve it by another key.

	Each index file requires a separate OPEN statement. When two or more OPEN statements specify the same master file for KEYED access, Business Rules automatically links each index file together so that when a record is added, deleted, or changed in the master file, every file in the group of index files is updated simultaneously. If there are any other index files that are not open in programs that could change the master file, you should run INDEX on them occasionally. At a minimum, you should update all index files every time you back up the master file. You also must replace (not reorganize with REORG) all index files after you copy the master file and remove deleted records (see the COPY command).		Each index file requires a separate OPEN statement. When two or more OPEN statements specify the same master file for KEYED access, Business Rules automatically links each index file together so that when a record is added, deleted, or changed in the master file, every file in the group of index files is updated simultaneously. If there are any other index files that are not open in programs that could change the master file, you should run INDEX on them occasionally. At a minimum, you should update all index files every time you back up the master file. You also must replace (not reorganize with REORG) all index files after you copy the master file and remove deleted records (see the [[COPY]] command).

	To run Business Rules programs on a multi-user system, OPEN statements should include a share parameter to specify what is to occur when a program at another workstation attempts to read or write to the same file. A share parameter is required (at least for the first OPEN statement) when several key files "share" the same master file. NOSHR may be used to exclude other workstations, but still share a master file with a group of index files at the same workstation~~. See the next section for more detailed information~~. For a complete description of the four share parameters, see ~~"share spec"~~ in the Definitions ~~chapter~~; see also ~~the~~ Multi-~~user~~ Programming ~~chapter~~.		To run Business Rules programs on a multi-user system, OPEN statements should include a share parameter to specify what is to occur when a program at another workstation attempts to read or write to the same file. A share parameter is required (at least for the first OPEN statement) when several key files "share" the same master file. NOSHR may be used to exclude other workstations, but still share a master file with a group of index files at the same workstation. For a complete description of the four share parameters, see [[Share Specs]] in the Definitions section; see also [[Multi-User Programming]].

	Lines 2100 to 2400 will open four key files for a file named FILE:		Lines 2100 to 2400 will open four key files for a file named FILE:
Line 79:		Line 79:

	===Open Statements===		===Open Statements===
			For each index file, there must be a separate [[OPEN]] statement.

	~~For each index file, there must be a separate OPEN statement.~~

	~~;Rules~~
	;The rules for setting up multiple index files are:		;The rules for setting up multiple index files are:
	:1.) The master file name (specified after NAME=) must be the same for all OPEN statements.		:1.) The master file name (specified after NAME=) must be the same for all OPEN statements.
Line 88:		Line 86:
	:3.) All share parameters must be consistent with the share parameter from the first OPEN statement encountered.		:3.) All share parameters must be consistent with the share parameter from the first OPEN statement encountered.

	The best and easiest way to achieve this is to omit share parameters after the first OPEN statement; in this case, Business Rules uses the share parameter from the first keyed OPEN statement for all subsequent keyed OPEN statements using the same master file. Share parameters may be coded explicitly after the first OPEN statement, but some combinations of share parameters across OPEN statements may cause error code 4148 at execution time (see the table of OPEN file restrictions in ~~the~~ Multi-User Programming ~~chapter~~ for more information). For example, line 290 will generate error code 4148 because the SHRI parameter in line 280 conflicts with the SHR parameter in line 290.		The best and easiest way to achieve this is to omit share parameters after the first OPEN statement; in this case, Business Rules uses the share parameter from the first keyed OPEN statement for all subsequent keyed OPEN statements using the same master file. Share parameters may be coded explicitly after the first OPEN statement, but some combinations of share parameters across OPEN statements may cause error code [[4148]] at execution time (see the table of OPEN file restrictions in [[Multi-User Programming]] for more information). For example, line 290 will generate error code 4148 because the SHRI parameter in line 280 conflicts with the SHR parameter in line 290.

	00280 OPEN #1: "name=FILE,kfname=KEY1,shri", INTERNAL,OUTIN,KEYED		00280 OPEN #1: "name=FILE,kfname=KEY1,shri", INTERNAL,OUTIN,KEYED
Line 98:		Line 96:
	00050 OPEN #2:"name=FILE,kfname=KEY2", INTERNAL,OUTIN,KEYED		00050 OPEN #2:"name=FILE,kfname=KEY2", INTERNAL,OUTIN,KEYED

	:5.) The group of OPEN statements for keyed processing with a single master file can mix INPUT, OUTIN or OUTPUT processing with one exception. The first OPEN must be OUTPUT or OUTIN if subsequent OPEN statements use OUTPUT or OUTIN. Error code 0608 occurs when a conflicting secondary OPEN statement is executed. Keys are only updated for files opened OUTPUT or OUTIN. This feature can save system overhead on files opened with INPUT, but should be used with caution because this method can lead to index files that do not match the recently changed master file. If you use this method, index files that are not updated should be replaced (not used with REORG) as soon as possible.		:5.) The group of OPEN statements for keyed processing with a single master file can mix INPUT, OUTIN or OUTPUT processing with one exception. The first OPEN must be OUTPUT or OUTIN if subsequent OPEN statements use OUTPUT or OUTIN. Error code [[0608]] occurs when a conflicting secondary OPEN statement is executed. Keys are only updated for files opened OUTPUT or OUTIN. This feature can save system overhead on files opened with INPUT, but should be used with caution because this method can lead to index files that do not match the recently changed master file. If you use this method, index files that are not updated should be replaced (not used with REORG) as soon as possible.

	In the example in lines 1100 to 1400, KEY1 and KEY2 will be automatically updated because they are opened OUTIN, but KEY3 and KEY4 will not be changed in this program.		In the example in lines 1100 to 1400, KEY1 and KEY2 will be automatically updated because they are opened OUTIN, but KEY3 and KEY4 will not be changed in this program.
Line 109:		Line 107:
	REWRITE #1 could change all four key fields in the master file, but KEY3 and KEY4 will not be updated because they are only opened for input.		REWRITE #1 could change all four key fields in the master file, but KEY3 and KEY4 will not be updated because they are only opened for input.

	:6.) New index files can be created at any time with the ~~Index_command~~. New index files can also be created with the OPEN statement, but only when creating a new (and empty) master file. To create a new master file and multiple new key files, you must code these four parameters: NEW (or USE or REPLACE), RECL=, KPS= and KLN= on all OPEN statements. For example:		:6.) New index files can be created at any time with the Index command. New index files can also be created with the OPEN statement, but only when creating a new (and empty) master file. To create a new master file and multiple new key files, you must code these four parameters: NEW (or USE or REPLACE), RECL=, KPS= and KLN= on all OPEN statements. For example:

	05100 OPEN #1:"name=MASTER,new,recl=31,kfname=KEY1,KPS=1,KLN=4,shr",INTERNAL,OUTIN,KEYED		05100 OPEN #1:"name=MASTER,new,recl=31,kfname=KEY1,KPS=1,KLN=4,shr",INTERNAL,OUTIN,KEYED
Line 116:		Line 114:
	Business Rules will remember when line 5200 is executed that the file was just created. It will create the new index file, and it will link file numbers 1 and 2 for multiple key processing.		Business Rules will remember when line 5200 is executed that the file was just created. It will create the new index file, and it will link file numbers 1 and 2 for multiple key processing.

	;Limit on Number of Open Files		====Limit on Number of Open Files====

	The number of key files that can be opened in Business Rules is restricted by the operating system maximum of open files for any single program.		The number of key files that can be opened in Business Rules is restricted by the operating system maximum of open files for any single program.

	For example, with DOS 2.x or greater, the Config.Sys file may set the FILES option to a maximum of 100. This allows you to open 95 files in addition to screen, printer, and other files automatically opened by Business Rules.		Each unique master file, index file or procedure file counts as one file against this open file limit. However, opening the same file under two or more different file numbers counts only once. Also, opened window files do not count against the operating system limit on open files.

	Let's examine the traditional maximum of 20 open files per program. As five files are needed by Business Rules 15 files are left for the program (technically, Unix / Linux versions could have 16 if the program does not use a printer). If a program is concerned only with multiple key access to a single file, the master file plus 14 key files could make up the 15 file limit; however, if two files are needed elsewhere in the program, only 12 key files could be used with the master file. If another program has only two master files, the program could have seven key files with one and six with another (or eight and five, or any combination that adds to 13, assuming no other files will be opened).

	~~The rules for total number of open files are the same in all versions of Business Rules.~~ Each unique master file, index file or procedure file counts as one file against this open file limit.

	However, opening the same file under two or more different file numbers counts only once. Also, opened window files do not count against the operating system limit on open files.

	~~;File Processing~~

			====File Processing====
	Rules for file processing with multiple key files are the same as rules for file processing with only one key file. Also, all aspects of file sharing, record locking and file name locking apply unchanged to multiple key files. The major addition is the use of different file numbers to provide access by different key fields.		Rules for file processing with multiple key files are the same as rules for file processing with only one key file. Also, all aspects of file sharing, record locking and file name locking apply unchanged to multiple key files. The major addition is the use of different file numbers to provide access by different key fields.

Line 138:		Line 128:
	There is a file pointer to keep track of the position in each index file; thus, reading sequentially by key is simply a matter of opening the file for keyed access, then using READ statements without any KEY or SEARCH parameter. By switching between READ statements with different the file numbers, a program could read sequentially by one key, then sequentially by a second key from a second key file, then come back to the first key file and pick up where the pointer was before the switch.		There is a file pointer to keep track of the position in each index file; thus, reading sequentially by key is simply a matter of opening the file for keyed access, then using READ statements without any KEY or SEARCH parameter. By switching between READ statements with different the file numbers, a program could read sequentially by one key, then sequentially by a second key from a second key file, then come back to the first key file and pick up where the pointer was before the switch.

	The KPS(n) and KLN(n) functions return key starting position and key length for the key file given in the OPEN statement for file n ~~(see also Split keys)~~.~~Split Key~~		The [[KPS]](n) and [[KLN]](n) functions return key starting position and key length for the key file given in the OPEN statement for file n.

	;Technique for Using Split Key Fields		====Technique for Using Split Key Fields====

	It is not necessary for all characters in a key field to be next to each other (sometimes called adjacent or contiguous). A key field may be split into as many as six fields with a maximum combined length of 128 bytes. When split keys with up to six sections are combined with multiple index files for a single master file, the indexing capabilities are quite powerful and flexible.		It is not necessary for all characters in a key field to be next to each other (sometimes called adjacent or contiguous). A key field may be split into as many as six fields with a maximum combined length of 128 bytes. When split keys with up to six sections are combined with multiple index files for a single master file, the indexing capabilities are quite powerful and flexible.

	For details of how to create an index file with split keys ~~sees~~ the ~~Index_command~~ or see the OPEN internal statement.		For details of how to create an index file with split keys see the [[Index]] command or see the [[OPEN internal]] statement.

	Also, to retrieve information about the individual sections of a key field, see the KPS and KLN functions.		Also, to retrieve information about the individual sections of a key field, see the [[KPS]] and [[KLN]] functions.

	To improve execution speed on sorted reports, some programmers have chosen to add another index file with a split key. For example, if a report is supposed to be sorted on three fields, you could maintain an index file with a split key consisting of those three fields in the desired order. When a report needs to be quickly generated on demand, a program can generate it immediately by reading sequentially by key using this existing index file. A general rule is that when you are frequently generating reports on small sections of the file, use indexing. When you are generating infrequent reports on major portions of files, sorting is more efficient.		To improve execution speed on sorted reports, some programmers have chosen to add another index file with a split key. For example, if a report is supposed to be sorted on three fields, you could maintain an index file with a split key consisting of those three fields in the desired order. When a report needs to be quickly generated on demand, a program can generate it immediately by reading sequentially by key using this existing index file. A general rule is that when you are frequently generating reports on small sections of the file, use indexing. When you are generating infrequent reports on major portions of files, sorting is more efficient.

Laura: /* FILE IO */

2013-04-08T19:05:03Z

FILE IO

← Older revision		Revision as of 19:05, 8 April 2013
Line 52:		Line 52:
	===BADKEYS===		===BADKEYS===
	The INDEX command may now specify BADKEYS or LISTBADKEYS to effect the same processing as DUPKEYS and LISTDUPKEYS performs. If both LISTBADKEYS and LISTDUPKEYS are specified, then all bad keys are listed ahead of dupkeys. They can be distinguished by whether or not they are duplicate.		The INDEX command may now specify BADKEYS or LISTBADKEYS to effect the same processing as DUPKEYS and LISTDUPKEYS performs. If both LISTBADKEYS and LISTDUPKEYS are specified, then all bad keys are listed ahead of dupkeys. They can be distinguished by whether or not they are duplicate.

	~~===FILE IO===~~
	~~A tool for simplifying working with index files is [[FILE IO]].~~

	==BTree Facility==		==BTree Facility==

Laura at 19:00, 8 April 2013

2013-04-08T19:00:46Z

← Older revision		Revision as of 19:00, 8 April 2013
Line 52:		Line 52:
	===BADKEYS===		===BADKEYS===
	The INDEX command may now specify BADKEYS or LISTBADKEYS to effect the same processing as DUPKEYS and LISTDUPKEYS performs. If both LISTBADKEYS and LISTDUPKEYS are specified, then all bad keys are listed ahead of dupkeys. They can be distinguished by whether or not they are duplicate.		The INDEX command may now specify BADKEYS or LISTBADKEYS to effect the same processing as DUPKEYS and LISTDUPKEYS performs. If both LISTBADKEYS and LISTDUPKEYS are specified, then all bad keys are listed ahead of dupkeys. They can be distinguished by whether or not they are duplicate.

			===FILE IO===
			A tool for simplifying working with index files is [[FILE IO]].

	==BTree Facility==		==BTree Facility==