Control statements for Concurrent Prefix Update

The FABYIN data set contains your description of the processing to be done by IMS™ HP Prefix Resolution while running a Concurrent Prefix Update job.

This control data set usually resides in the input stream. However, it can also be defined as a member of a sequentially partitioned data set.

Syntax rules

The length of the FABYIN data set must be fixed at 80 bytes. BLKSIZE, if specified, must be a multiple of 80.

The control statements must conform to the following syntax rules:

A control statement is a keyword followed by an equal sign (=) and a value.
A keyword and its value or values must be on a single line and must be specified between columns 1 - 80, both inclusive.
For each control statement, any number of leading blanks can be specified for the purpose of indentation.
A statement keyword must be separated from its associated value by an equal sign (=). The equal sign must not be preceded or followed by blanks.
A line that starts with an asterisk (*) in column 1 is treated as a comment line.
You can specify Y for YES and N for NO, except for ITKBSRVR and ITKBLOAD control statements.

Description of control statements

The following control statements can be used for Concurrent Prefix Update.

ALLOWLC

ALLOWLC specifies whether to allow the existence of logical children that do not have logical parents.

This control statement is optional. If you do not specify this control statement, ALLOWLC=NO is used.


            .-NO--.   
>>-ALLOWLC=-+-YES-+--------------------------------------------><

NO: Specifies to end the Prefix Resolution function with message FABY879A when logical children that do not have logical parents exist.
YES: Specifies to allow the existence of logical children that do not have logical parents. Message FABY879W is issued.

Tip: The default value of this control statement can be changed with site default options.

ALLOWLP

ALLOWLP specifies whether to allow logical parents that do not have logical children.

This control statement is optional. If you do not specify this control statement, ALLOWLP=YES is used.


            .-YES-.   
>>-ALLOWLP=-+-NO--+--------------------------------------------><

YES: Specifies to allow the existence of logical parents that do not have logical children.
NO: Specifies to end the Prefix Resolution function with message FABY878A when logical parents that do not have logical children exist.

Tip: The default value of this control statement can be changed with site default options.

AVGRLEN

AVGRLEN specifies the estimated average length of logical pointer records in the DFSURWF1 input data set.

This control statement is optional. If the AVGRLEN control statement is provided, space utilization of the LPLCWKnn, the TWINWKnn, or the SORTWKnn data sets and performance can be improved.


>>-AVGRLEN=nnn-------------------------------------------------><

nnn: Specify a value in the range of 1 - 999. Leading zeros are optional for value nnn.

Note: The value you can specify for this control statement is a performance sensitive parameter. You can determine the value for this control statement by using DFSORT statistics.

DBRC

DBRC specifies whether the Prefix Update function uses DBRC.

This control statement is optional. If you do not specify this control statement, DBRC=YES is used.


         .-YES-.   
>>-DBRC=-+-NO--+-----------------------------------------------><

YES: Specifies to use DBRC.
NO: Specifies not to use DBRC unless the DBRC=FORCE option is specified during the IMS system generation or in the DFSIDEF0 module.

Tip: The default value of this control statement can be changed with site default options.

DEBUG

DEBUG specifies whether to turn on the debug function.

This control statement is optional. If you do not specify this control statement, DEBUG=NO is used.


          .-NO-.   
>>-DEBUG=-+-A--+-----------------------------------------------><

NO: Specifies not to turn on the debug function.
A: Specifies to turn on the debug function. Additional FABY011I messages are issued to show the progress of sort with sort exits E15 and E35.

FILSZ

FILSZ specifies the estimated number of logical pointer records in the DFSURWF1 input data set.

This control statement is optional. If the FILSZ control statement is provided, space utilization of the LPLCWKnn, the TWINWKnn, or the SORTWKnn data sets and performance can be improved.


>>-FILSZ=nnnnnnnnn---------------------------------------------><

nnnnnnnnn: Specify a value in the range of 1 - 999999999. Leading zeros are optional for value nnnnnnnnn.

When estimating the value of the FILSZ control statement, remember that there are one or more logical pointer records for each occurrence of the source database segments that have a logical relationship to other segments in the same or other databases (as specified in the DBD).

For such logical relationships, there is one record for:

Each logical parent
Each of its logical children
The last logical child (if used)
Each logical twin forward and backward pointer

Note: The value you can specify for this control statement is a performance sensitive parameter. You can determine the value for this control statement by using DFSORT statistics.

HPPRBH

HPPRBH specifies whether the Prefix Update function uses the HPPR buffer handler to update OSAM data sets.

This control statement is optional. If you do not specify this control statement, HPPRBH=YES is used.


           .-YES-.   
>>-HPPRBH=-+-NO--+---------------------------------------------><

YES

Specifies to use HPPR buffer handler to update OSAM data sets.

NO

Specifies to use the IMS DL/I buffer handler to update OSAM data sets. If OSAM data sets to be updated are large format data sets, you must specify HPPRBH=NO.

If the DFSCTL DD statement is not specified in the JCL, the data set is allocated dynamically to activate IMS OSAM sequential buffering.

Requirements:

IMS.SDFSRESL must be concatenated behind the DD statement that contains the IMS HP Prefix Resolution load library.
If JOBLIB or STEPLIB is not authorized by having unauthorized libraries that are concatenated to IMS.SDFSRESL, the DFSRESLB DD statement must be included.

Tip: The default value of this control statement can be changed with site default options.

ITKBLOAD

ITKBLOAD specifies the name of the load module library for IMS Tools Knowledge Base.

This control statement is optional and used only when ITKBSRVR=server_name is specified. If you do not specify this control statement, ITKBLOAD=*NO is used and IMS HP Prefix Resolution attempts to load an IMS Tools Knowledge Base module from the STEPLIB libraries.


             .-*NO----------.   
>>-ITKBLOAD=-+-library_name-+----------------------------------><

*NO: Specifies that the IMS Tools Knowledge Base modules are loaded from the private library or the system library of the job.
library_name: Specifies the name of the IMS Tools Knowledge Base load module data set that is to be used by IMS HP Prefix Resolution.

Tip: The default value of this control statement can be changed with site default options.

ITKBSRVR

ITKBSRVR specifies the name of the IMS Tools Knowledge Base server.

This control statement is optional. If you do not specify this control statement, ITKBSRVR=*NO is used.


             .-*NO---------.   
>>-ITKBSRVR=-+-server_name-+-----------------------------------><

*NO

Specifies that IMS HP Prefix Resolution does not store reports in the IMS Tool Knowledge Base Output repository.

server_name

Specifies that IMS HP Prefix Resolution stores reports in the IMS Tools Knowledge Base Output repository of the specified server.

If ITKBSRVR=server_name is specified, IMS HP Prefix Resolution attempts to connect to the server and then to store the following reports in the IMS Tools Knowledge Base Output repository:

FABYIN Control Statements report
Statistics report
Update Processing Summary report

ITKBSRVR=server_name requires that an appropriate version of IMS Tools Knowledge Base is installed and the server is started. For more information, see Software and hardware requirements and Configuring the IMS Tools Knowledge Base server.

Tip: The default value of this control statement can be changed with site default options.

OPRTLC

OPRTLC specifies whether logical children with no logical parents are printed in the Orphan Records report.

This control statement is optional. If you do not specify this control statement, OPRTLC=YES is used.


           .-YES-.   
>>-OPRTLC=-+-NO--+---------------------------------------------><

YES: Specifies to print logical children that do not have logical parents.
NO: Specifies not to print logical children that do not have logical parents.

Tip: The default value of this control statement can be changed with site default options.

OPRTLP

OPRTLP specifies whether logical parents with no logical children are printed in the Orphan Records report.

This control statement is optional. If you do not specify this control statement, OPRTLP=NO is used.


           .-NO--.   
>>-OPRTLP=-+-YES-+---------------------------------------------><

NO: Specifies not to print logical parents that do not have logical children.
YES: Specifies to print logical parents that do not have logical children.

Tip: The default value of this control statement can be changed with site default options.

PIPEBLKSZ

PIPEBLKSZ specifies how many records can be moved to and from a pipe used by the HPPRPIPE service per transmission.

Recommendation: Consider specifying this control statement only when you finish tuning other parameters because the performance of HPPRPIPE depends on various factors and this control statement can degrade performance.

The block size you specify for PIPEBLKSZ must include the data length (up to 32,756 bytes) plus 4 bytes for the internal block descriptor word (BDW).

If you change the PIPEBLKSZ specification, you might need to change the value of the REGION parameter to avoid running out of virtual storage.


              .-32768---.               
>>-PIPEBLKSZ=-+---------+-+---------+--------------------------><
              '-blksize-' |   .-*-. |   
                          '-,-+---+-'   
                              +-1-+     
                              +-2-+     
                              +-3-+     
                              '-4-'

The first parameter blksize specifies the block size for the pipe identified by the second parameter, which specifies a pipe ID.

The default block size is 32768 for each pipe. If the blksize value is not specified, the default value is used for the specified pipe ID. If only the blksize value is specified, or the blksize value is specified with pipe ID *, it overrides the default block size. The maximum blksize value is 262144, and the minimum value is 1024. The minimum value must be larger than or equal to the maximum length of the records you are to transfer through the pipe, plus four.

Pipe IDs: Pipe ID is a number that identifies a pipe allocated between tasks running in an IMS HP Prefix Resolution job. You can specify one of the following pipe IDs:

1: The pipe between secondary index processing (INDX sort task) and logical parent/logical child processing (LPLC sort task) in the Prefix Resolution function. This pipe is allocated only when both INDX sort and LPLC sort are used in Stand-Alone Prefix Resolution or Concurrent Prefix Update jobs.
2: The pipe to eliminate the intermediate Work File 2 (WF2) data set that is used in the Prefix Resolution function. This pipe is not allocated when WF2 type data is not required. For example, the pipe is not allocated in Stand-Alone Prefix Update jobs.
3: The pipe to eliminate the intermediate Work File 3 (WF3) data set that is used between the Prefix Resolution process and the Prefix Update process. This pipe is not allocated when WF3 type data is not required. For example, the pipe is not allocated in Stand-Alone Prefix Resolution or Stand-Alone Prefix Update jobs.
4: The pipe that is used internally in Prefix Update jobs. For example, the IMS DL/I buffer handler task, which updates OSAM data sets, allocates this pipe.
*: All four pipes. The value of all pipes are changed if you omit the pipe ID or specify an asterisk (*) for the pipe ID.

PIPEDEPTH

PIPEDEPTH specifies the number of blocks that can be in a pipe used by the HPPRPIPE service at any given time before the pipe becomes full.

The use of large values for PIPEDEPTH enables the HPPRPIPE service to accumulate more information in virtual storage. This can be helpful in smoothing out periodic wait periods during which the writing task is forced to wait because the pipe temporarily becomes full. The pipe becomes full because the reading task is temporarily delayed in reading data from the pipe.

If you change the PIPEDEPTH specification, you might need to change the value of the REGION parameter to avoid running out of virtual storage.


              .-30----.               
>>-PIPEDEPTH=-+-------+-+---------+----------------------------><
              '-depth-' |   .-*-. |   
                        '-,-+---+-'   
                            +-1-+     
                            +-2-+     
                            +-3-+     
                            '-4-'

The first parameter depth specifies the number of blocks that can be held in the pipe, which is identified by the second parameter, at any given time before the pipe becomes full. The second parameter specifies a pipe ID.

The default number of blocks is 30 for each pipe. If the depth value is not specified, the default value is used for the specified pipe ID. If only the depth value is specified, or the depth value is specified with pipe ID *, it overrides the default number of blocks. The maximum value is 1792, and the minimum value is 2.

Pipe IDs: Pipe ID is a number that identifies a pipe allocated between tasks running in an IMS HP Prefix Resolution job. You can specify one of the following pipe IDs:

1: The pipe between secondary index processing (INDX sort task) and logical parent/logical child processing (LPLC sort task) in the Prefix Resolution function. This pipe is allocated only when both INDX sort and LPLC sort are used in Stand-Alone Prefix Resolution or Concurrent Prefix Update jobs.
2: The pipe to eliminate the intermediate Work File 2 (WF2) data set that is used in the Prefix Resolution function. This pipe is not allocated when WF2 type data is not required. For example, the pipe is not allocated in Stand-Alone Prefix Update jobs.
3: The pipe to eliminate the intermediate Work File 3 (WF3) data set that is used between the Prefix Resolution process and the Prefix Update process. This pipe is not allocated when WF3 type data is not required. For example, the pipe is not allocated in Stand-Alone Prefix Resolution or Stand-Alone Prefix Update jobs.
4: The pipe that is used internally in Prefix Update jobs. For example, the IMS DL/I buffer handler task, which updates OSAM data sets, allocates this pipe.
*: All four pipes. The value of all pipes are changed if you omit the pipe ID or specify an asterisk (*) for the pipe ID.

PIPEWAIT

PIPEWAIT specifies the amount of time a writer or a reader of a pipe can remain in a wait state before the HPPRPIPE service issues a message and ends abnormally.


>>-PIPEWAIT=-+------+-+------------------------+---------------><
             '-time-' |   .-*-.                |   
                      '-,-+---+-+------------+-'   
                          +-1-+ |   .-RDWR-. |     
                          +-2-+ '-,-+------+-'     
                          +-3-+     '-OPEN-'       
                          '-4-'

The first parameter time specifies the amount of time that a reader or a writer that connects to the pipe, which is identified by the second parameter, can remain in a wait state. The second parameter specifies a pipe ID. The third parameter specifies the target to apply the wait state. The default value RDWR is used when the third parameter is not specified.

Pipe IDs: Pipe ID is a number that identifies a pipe allocated between tasks running in an IMS HP Prefix Resolution job. You can specify one of the following pipe IDs:

1: The pipe between secondary index processing (INDX sort task) and logical parent/logical child processing (LPLC sort task) in the Prefix Resolution function. This pipe is allocated only when both INDX sort and LPLC sort are used in Stand-Alone Prefix Resolution or Concurrent Prefix Update jobs.
2: The pipe to eliminate the intermediate Work File 2 (WF2) data set that is used in the Prefix Resolution function. This pipe is not allocated when WF2 type data is not required. For example, the pipe is not allocated in Stand-Alone Prefix Update jobs.
3: The pipe to eliminate the intermediate Work File 3 (WF3) data set that is used between the Prefix Resolution process and the Prefix Update process. This pipe is not allocated when WF3 type data is not required. For example, the pipe is not allocated in Stand-Alone Prefix Resolution or Stand-Alone Prefix Update jobs.
4: The pipe that is used internally in Prefix Update jobs. For example, the IMS DL/I buffer handler task, which updates OSAM data sets, allocates this pipe.
*: All four pipes. The value of all pipes are changed if you omit the pipe ID or specify an asterisk (*) for the pipe ID.

RDWR

Specifies to apply the wait state to the read and write wait state of the pipe.

When you specify RDWR, the first parameter time specifies, in minutes, how long a writer or a reader for the pipe can remain in a wait state. The value can be in the range of 1 - 1440.

The default is 1440 minutes for pipe ID 1 and 4, and 15 minutes for pipe ID 2 and 3. If the time value is specified with no pipe ID, or the time value is specified with pipe ID *, it overrides the default time value for all pipes.

OPEN

Specifies to apply the wait state to the open wait state of the pipe.

When you specify OPEN, the first parameter time specifies, in seconds, how long a writer or a reader for the pipe can remain in a wait state. The value can be in the range of 1 - 1440.

The default is 30 seconds for each pipe. If the time value is specified with no pipe ID, or the time value is specified with pipe ID *, it overrides the default time value for all pipes.

SKIPLCR3

SKIPLCR3 specifies whether to suppress generating the intermediate Work File 3 (WF3) records for logical child segments when the logical child segments have no direct pointers, such as direct LP and direct LT pointers.

This control statement is optional. The default is SKIPLCR3=NO, which means that WF3 records are generated for all logical child segments.


             .-NO--.   
>>-SKIPLCR3=-+-YES-+-------------------------------------------><

NO: Generates WF3 records for all logical child segments.
During the prefix update processing, the Prefix Update function skips the WF3 records for logical child segments that have no direct pointers. Reason code 03 is printed in the Update Processing Summary report to indicate that such segments were skipped.
YES: Does not generate WF3 records for logical child segments that have no direct pointers.
SKIPLCR3=YES can improve the performance of the job.

TYPE

TYPE specifies the type of processing for the Prefix Resolution function.

This control statement is required.


>>-TYPE=--+-LO-+-----------------------------------------------><
          +-LM-+   
          +-IO-+   
          '-IM-'

LO: Stands for Logical pointers Only, and specifies that only the logical pointer resolution is run. Secondary index processing is not run, and the DFSURIDX data set is not created.
LM: Stands for Logical pointers Mainly, and specifies that most records in the DFSURWF1 input data set are records for logical pointer resolution. Both logical pointer resolution and secondary index processing are run.
IO: Stands for Index pointers Only, and specifies that only secondary index processing is run. Logical pointer resolution is not run, and the DFSURWF3 data set is not created.
IM: Stands for Index pointers Mainly, and specifies that most records in the DFSURWF1 data set are records for secondary index processing. Both logical pointer resolution and secondary index processing are run.

When both logical pointer resolution and secondary index processing are to be run, you can improve performance by correctly specifying LM or IM. If you are running the function for the first time and you are not sure whether your database contains more logically related records or more secondary index records, make an educated guess.

Choosing the TYPE option determines the DD specifications that are required. If you specify TYPE=IM or TYPE=LM, the DFSURIDX DD statement is required.

Note: The value you can specify for this control statement is a performance sensitive parameter. You can determine the value for this control statement by using DFSORT statistics.

UPDATE

UPDATE specifies the function of IMS HP Prefix Resolution.

This control statement is required. If you do not specify this control statement, UPDATE=NO is used.

To use Concurrent Prefix Update, you must specify UPDATE=YES.


            .-NO---.   
>>-UPDATE=--+-YES--+-------------------------------------------><
            '-ONLY-'

NO: Specifies to run only the Prefix Resolution function.
YES: Specifies to run the Prefix Resolution and the Prefix Update function in a single job step.
ONLY: Specifies to run only the Prefix Update function.

Tip: The default value of this control statement can be changed with site default options.

UPDLPC

UPDLPC specifies whether the Prefix Update function updates counter fields of the logical parents. The UPDLPC control statement is valid only if DBIL control statement of the IMS Database Prereorganization utility is specified for the database.

This control statement is optional. If you do not specify this control statement, UPDLPC=YES is used.


           .-YES-.   
>>-UPDLPC=-+-NO--+---------------------------------------------><

YES: Specifies to update counter fields of the logical parents even when they have no logical children. When you delete all of the logical children of a logical parent during the DBIL-type reorganization process, you must specify this parameter.
Note: The performance of the Prefix Update function will decline if you specify this parameter.
NO: Specifies not to update counter fields of the logical parents that have no logical children.

Tip: The default value of this control statement can be changed with site default options.

WF2OUT

WF2OUT specifies whether to use the intermediate Work File 2 (WF2) data set instead of the HPPRPIPE service.

Tip: The value you can specify for this control statement is a performance sensitive parameter. If high CPU time consumption or large sort work space to run two DFSORT tasks concurrently is the problem, WF2OUT=YES can resolve it. Otherwise, the performance of the Prefix Resolution function declines if you specify this parameter.

This control statement is optional. The default is WF2OUT=NO, which means that the WF2 data set is not used.

Recommendation: Because this control statement can degrade performance, specify this control statement after you finish tuning other parameters.


            .-NO--.   
>>-WF2OUT=--+-YES-+--------------------------------------------><

NO

Does not use the WF2 data set. HPPRPIPE is used instead.

Specifying WF2OUT=NO can eliminate much of the I/O and handling of the tape and DASDs, as well as the allocation of the DASDs that are associated with the WF2 data set.

YES

Uses the WF2 data set.

If you specify WF2OUT=YES, you must also specify the FABYWF2 DD statement.

If you specify WF2OUT=YES, the SORTWKnn DD statements are used instead of the LPLCWKnn DD statements. Also, TWINWKnn DD statements are not used because the TWIN sort reuses the SORTWKnn data sets.

Specifying WF2OUT=YES can eliminate CPU time associated with the HPPRPIPE service, and reduce the space required for the sort work data sets.

XAVGRLEN

XAVGRLEN specifies the estimated average length of secondary index records in the DFSURWF1 input data set.

This control statement is optional. If the XAVGRLEN control statement is provided, both space utilization of the INDXWKnn data sets and performance can be improved.


>>-XAVGRLEN=nnn------------------------------------------------><

nnn: Specify a value in the range of 1 - 999. Leading zeros are optional for value nnn.

Note: The value you can specify for this control statement is a performance sensitive parameter. You can determine the value for this control statement by using DFSORT statistics.

XFILSZ

XFILSZ specifies the estimated number of secondary index records in the DFSURWF1 input data set.

This control statement is optional. If the XFILSZ control statement is provided, both space utilization of the INDXWKnn data sets and performance can be improved.


>>-XFILSZ=nnnnnnnnn--------------------------------------------><

nnnnnnnnn: Specify a value in the range of 1 - 999999999. Leading zeros are optional for value nnnnnnnnn.

The value that you specify for XFILSZ should indicate that one secondary index record exists for each occurrence of the source database segments that were identified in the DBD as having a secondary index.

Note: The value you can specify for this control statement is a performance sensitive parameter. You can determine the value for this control statement by using DFSORT statistics.