Initialize - 0 Call - Finalist - 10.0

Finalist Compatibility Interface (CI) Migration Guide

Product type
Software
Portfolio
Verify
Product family
Data Quality - Postals
Product
Finalist
Version
10.0
Language
English
Product name
Finalist
Title
Finalist Compatibility Interface (CI) Migration Guide
Copyright
2023
First publish date
1998
ft:lastEdition
2024-05-15
ft:lastPublication
2024-05-15T00:18:43.325870

The CI Initialize (0) call is called PBFNInit (PBFNINIT) in the native interface. The parameter passed in to PBFNInit is called SetupDef (PBFNGCFG copybook). Details of how to migrate from the Finalist callarea to the SetupDef structure are covered below. All CI initialization options are covered in the SetupDef structure along with additional options that are not available in the CI.

The PBFNInit API initializes the Finalist environment and generates a return code to indicate success or failure. A successful call generates a return code of one (1). Other positive numbers indicate success but include a warning that something may not be right. For example, the Finalist database may be about to expire. A zero (0) or negative value(-1) indicates a failure of the initialization. In all cases, a PBFNTerminate call should ultimately be done to ensure all storage allocated by Finalist has been released. A call to PBFNProcess should not be done if PBFNInit generates a zero (0) or negative (-1) return code.

There are two methods available for using PBFNInit to initialize the Finalist environment.

  1. You can pass in (or allow to default) all parameters in the SetupDef structure, or you can tell Finalist to read in a configuration file (typically DD:PBFNCFG) or a combination of both. This is controlled via the PBFN-GCFG-LOADSETUP field. Any field passed in via the SetupDef structure will override the matching option in DD:PBFNGCFG. You can use this to force required options (for example, CASS parameters) while allowing others (for example, report DD names) to be modified dynamically.

  2. In the second option, applications initialize the CI using the SetupDef structure. This is a hybrid solution and common where applications are already using options that do not exist in the CI. It is mentioned here in case you encounter this situation in your code. For that interface, COBOL applications would specify FINAL-USE-SETUP-Y or FINAL-USE-SETUPDEF = Y. The CI then uses the pre-populated PBFN-GCFG-SETUP as part of the CI parameter file instead of the CI fields when internally calling PBFNInit. In that case, the application logic is already using PBFN-GCFG-SETUP and therefore no additional cross-mapping needs to be done to directly call PBFNInit.

The next section covers how to convert many, but not all, fields from the "0" callarea to the SetupDef structure. First, you must initialize the SetupDef structure. In COBOL, use this statement:

INITIALIZE PBFN-GCFG-SETUP.

Many options in LPFNCL01 (CALLAREA) are specified as Y|N. In SetupDef (PBFNGCFG), the same options are ON|OFF.