In This Chapter
This chapter explains how to customize the format in which Databridge outputs data set records and use those custom formats with DBSpan, DBSnapshot, or a user-written Databridge Accessory.
Record formatting procedures allow you to customize the format in which Databridge outputs data set records and use those custom formats with DBSpan, DBSnapshot, or a user-written Databridge Accessory. If you want to reformat data items in a data set to different layouts, see Altered Data Sets for more information.
Sample ALGOL External Formatting Procedure contains the sample external formatting procedure, SYMBOL/DATABRIDGE/SAMPLE/ENCRYPT.
Using Custom Formatting Procedures
To customize how you want to output your data set records using a formatting procedure, complete the following steps:
- Read this entire chapter so that you get an understanding of how the code you write for your formatting procedure relates to the actual FORMAT declarations you make in the DBGenFormat file.
- Look at the data records you want to convert so you can get an idea of how many formatting routines you need to code.
- Familiarize yourself with the sample in Sample ALGOL External Formatting Procedure, which illustrate how to write a formatting procedure.
Use CANDE or another editor to retrieve the DBGenFormat parameter file DATA/GENFORMAT/SAMPLE/CONTROL.
For a general description of the DBGenFormat parameter file, refer to the Databridge Host Administrator's Guide. 5. Rename the file, as follows:
where databasename is the name of the database for which you are creating the tailored support library.
Declare the formatting procedure. See Declaring Internal and External Formatting Procedures for more information.
Write the formatting routine as follows:
If you Do this Declared an internal formatting procedure Write the formatting procedure patch file that contains the formatting procedure. For details, see Writing an Internal Formatting Routine. Declared an external formatting procedure Write the formatting procedure library source file that contains the formatting routine. For details, see Writing an External Formatting Routine.
You do not have to complete the external library file before going on to the next step. You must, however, finish writing and compiling it before you run an Accessory that uses the external format.
If you wrote an external formatting procedure (SYMBOL/DATABRIDGE/formattingroutine), compile it as OBJECT/DATABRIDGE/formattingroutine or whatever you called it in the DBGenFormat parameter file.
Compile the tailored support library, as follows:
START WFL/DATABRIDGE/COMP ("SUPPORT",
The literal that represents the DBSupport program
The quotation marks are required.
The name of the database for which you are creating the tailored support library.
The database name can include a usercode and pack, which are used to locate the database DESCRIPTION file, as follows:
"(usercode)databasename ON packname"
The quotation marks are required.
"logicaldatabasename" The name of a logical database for which you are creating the tailored support library.
This WFL compiles layout tables for each data set in the database designated by databasename or logicaldatabasename. This results in the new tailored support library titled as follows:
— or —
These data set-specific layout tables contain the offsets and sizes of individual data items.
If you have two databases with the same name under different usercodes, and you are running Databridge from a third usercode, be careful when you create a tailored support library. In this case, the second library you compile overwrites the first, because Databridge strips the usercode and pack name from the database name to create the tailored support library title.
In the Accessory parameter file, enter the tailored support library name for the SUPPORT option and enter the ALGOL formatting procedure name for the FORMAT option.
For more information, refer to the Databridge Host Administrator's Guide.
What to Do Next
You can now run your Databridge Accessories as usual.
Repeat these steps for each internal or external formatting procedure you want to use.
If you encounter problems, see Troubleshooting for troubleshooting information. The Troubleshooting chapter provides specific troubleshooting tips for writing formatting procedures.
Declaring Internal and External Formatting Procedures
Formatting procedures must be declared as an internal or external format in the DBGenFormat parameter file. Declare the formatting procedure in the DBGenFormat parameter file using the syntax below in Declaring Internal Formats and Declaring External Formats.
Consider the following information before you choose whether to declare an internal or external formatting procedure:
|Internal Format Description||External Format Description|
|Internal formats are compiled as patches to your tailored support library. This requires that you recompile DBSupport via WFL/DATABRIDGE/COMP each time you update the internal formatting routine.||External formats are linked at run-time to a user-written format library, so they can be recompiled any time without having to recompile DBSupport.|
|Internal formats do not have to specify how to link to DBEngine or DBSupport.||External formats must link to DBSupport and DBEngine at the proper time.|
|Internal formats do not have to verify that their interface version matches DBEngine.||External format libraries must ensure that their interface version matches DBEngine.|
Declaring Internal Formats
To declare the formatting procedure as an internal format, use the following syntax in the DBGenFormat parameter file:
INTERNAL FORMAT formattingprocedure IN "patchfiletitle"
where formattingprocedure is the formatting procedure that you declared, and patchfiletitle is the title of the ALGOL patch file containing the internal formatting procedure that you created.
Declaring External Formats
If you want to write your own ALGOL library for a format, you can reference it in the tailored support library by using the following syntax in the DBGenFormat parameter file:
EXTERNAL FORMAT formattingprocedure IN "objectfilename"
where formattingprocedure is the name you have given to the external formatting procedure and objectfilename is the file title of your compiled ALGOL library program.
Writing Formatting Routines
Although you must code the formatting procedure in ALGOL, you can code it to call a COBOL library that actually formats the data set record.
Initializing the Formatting Routine.
You must initialize your formatting routine the first time it is called. Initializing your formatting routine allows you to obtain information, such as structure numbers and indexes. Your formatting routine uses this information to identify and format records. You can use the following entry points to obtain this information:
Writing an Internal Formatting Routine
If you declared an internal format in DBGenFormat, you must write an ALGOL patch file containing the formatting procedure. The patch file may include global declarations in addition to the formatting procedure itself. The patch file should not include the EXPORT declaration for the formatting routine. DBGenFormat automatically generates the appropriate EXPORT declaration.
Writing an External Formatting Routine
If you declared an external format in DBGenFormat, you must write your own library that contains the formatting procedure and does the following:
Sets the $ INCLUDE_ENGINE option (and the $INCLUDE_SUPPORT option if you call any DBSupport entry points) and includes SYMBOL/DATABRIDGE/INTERFACE using the following ALGOL $INCLUDE statements:
$SET INCLUDE_ENGINE INCLUDE_SUPPORT
Do not invoke the DBLINKENGINE define to link to DBEngine because DBSupport automatically links your library to the correct instance of DBEngine. If you invoke the DBLINKENGINE define before the library freezes, your library will link to a different instance of DBEngine than the Accessory, and it might return incorrect information and errors.
Do not try to call any entry points before your library freezes because it gets linked to a different instance of DBEngine and/or DBSupport.
Calls DBINTERFACEVERSION to verify that your program was compiled against the same API file (SYMBOL/DATABRIDGE/INTERFACE) as DBEngine.
Do not call DBINITIALIZE. DBINITIALIZE will undo the initialization that the Accessory has already done.
The following example shows how to call DBINTERFACEVERSION:
DBMTYPE DBRslt; DBRslt := DBInterfaceVersion (DBV_VERSION, "MyFormat:"); if DBRslt NEQ DBM_OK then begin DBDisplayMsg (DBRslt); MYSELF.STATUS := value (TERMINATED); end;
See SYMBOL/DATABRIDGE/SAMPLE/ENCRYPT in Sample ALGOL External Formatting Procedure as an example of an external formatting routine.
Calling a COBOL Library
If your formatting routine calls a COBOL formatting program that is compiled with $FEDLEVEL=5, then you must do the following where the library is invoked:
In the COBOL program's entry point declaration, specify the ACTUALNAME to match the PROGRAM- ID name in the COBOL program. For example, the sample COBOL program EXTRACTADDRESS has the following:
IDENTIFICATION DIVISION. PROGRAM-ID. EXTRACTADDRESS.
The declaration of the COBOL program's entry point in the ALGOL formatting routine would look like the following:
procedure ExtractAddress (...); library ExtractAddressLib (ACTUALNAME = "EXTRACTADDRESS");
See the declaration of EXTRACTADDRESS in Sample ALGOL Virtual Transform Procedure.
Sample ALGOL External Formatting Procedure
This formatting procedure (SYMBOL/DATABRIDGE/SAMPLE/ENCRYPT) illustrates how to write an external format that encrypts each update record using a translate table. The program that reads these records must reverse the translation to see the original values.
The DBGenFormat declaration for this example is as follows:
EXTERNAL FORMAT ENCRYPT IN "OBJECT/DATABRIDGE/SAMPLE/ENCRYPT"
The ALGOL source code (SYMBOL/DATABRIDGE/SAMPLE/ENCRYPT) for this example is as follows:
$ SET OMIT 09000000 ------------------------------------------------------------------------ 09000100 09000110 (c) Copyright 2019 Micro Focus or one of its affiliates. 09000120 09000130 Module: SYMBOL/DATABRIDGE/SAMPLE/ENCRYPT 09000140 09000150 Project: Databridge 09000160 09000170 Description: Databridge Encryption Format Library Program 09000180 09000190 09000430 ------------------------------------------------------------------------ 09000440 09002000 09002100 Modification history 09002200 -------------------- 09002300 09002400 Version 41.473 09002500 Initial version. 09002600 09002700 This sample Databridge library program illustrates how to write 09002800 an external format. It uses a translate table to perform a 09002900 simple encryption on each update record. A program reading such 09003000 records would have to reverse the translation to see the 09003100 original values. 09003200 09003300 Version 41.485 09003400 1 Added DBInterface compatibility check. 09003500 09003600 End History 09003700 $ POP OMIT 09003800 09003900 09004100 $ VERSION 06.003.0000 09999900Version $ SET SEQ 40000000 40000000 40001000 begin 40002000 40003000 $ set INCLUDE_ENGINE 40004000 $ include "SYMBOL/DATABRIDGE/INTERFACE" 40005000 40006000 translatetable 40007000 Encryption 40008000 ( 40009000 48"000102030405060708090A0B0C0D0E0F" 40010000 48"101112131415161718191A1B1C1D1E1F" 40011000 48"202122232425262728292A2B2C2D2E2F" 40012000 48"303132333435363738393A3B3C3D3E3F" 40013000 48"404142434445464748494A4B4C4D4E4F" 40014000 48"505152535455565758595A5B5C5D5E5F" 40015000 48"606162636465666768696A6B6C6D6E6F" 40016000 48"707172737475767778797A7B7C7D7E7F" 40017000 48"808182838485868788898A8B8C8D8E8F" 40018000 48"909192939495969798999A9B9C9D9E9F" 40019000 48"A0A1A2A3A4A5A6A7A8A9AAABACADAEAF" 40020000 48"B0B1B2B3B4B5B6B7B8B9BABBBCBDBEBF" 40021000 48"C0C1C2C3C4C5C6C7C8C9CACBCCCDCECF" 40022000 48"D0D1D2D3D4D5D6D7D8D9DADBDCDDDEDF" 40023000 48"E0E1E2E3E4E5E6E7E8E9EAEBECEDEEEF" 40024000 48"F0F1F2F3F4F5F6F7F8F9FAFBFCFDFEFF" 40025000 40026000 to 40027000 40028000 48"FFFEFDFCFBFAF9F8F7F6F5F4F3F2F1F0" 40029000 48"EFEEEDECEBEAE9E8E7E6E5E4E3E2E1E0" 40030000 48"DFDEDDDCDBDAD9D8D7D6D5D4D3D2D1D0" 40031000 48"CFCECDCCCBCAC9C8C7C6C5C4C3C2C1C0" 40032000 48"BFBEBDBCBBBAB9B8B7B6B5B4B3B2B1B0" 40033000 48"AFAEADACABAAA9A8A7A6A5A4A3A2A1A0" 40034000 48"9F9E9D9C9B9A99989796959493929190" 40035000 48"8F8E8D8C8B8A89888786858483828180" 40036000 48"7F7E7D7C7B7A79787776757473727170" 40037000 48"6F6E6D6C6B6A69686766656463626160" 40038000 48"5F5E5D5C5B5A59585756555453525150" 40039000 48"4F4E4D4C4B4A49484746454443424140" 40040000 48"3F3E3D3C3B3A39383736353433323130" 40041000 48"2F2E2D2C2B2A29282726252423222120" 40042000 48"1F1E1D1C1B1A19181716151413121110" 40043000 48"0F0E0D0C0B0A09080706050403020100" 40044000 ); 40045000 40046000 boolean FirstTime; 40047000 40048000 DBFormatHead [Encrypt]; 40049000 % ------- 40050000 begin 40051000 real Len; 40052000 pointer pRec; 40053000 40054000 if FirstTime then 40055000 begin 40056000 DBMTYPE DBRslt; 40057000 40058000 DBRslt := DBInterfaceVersion (DBV_VERSION, "Encrypt:"); 40059000 if DBRslt NEQ DBM_OK then 40060000 begin 40061000 DBDisplayMsg (DBRslt); 40062000 MYSELF.STATUS := value (TERMINATED); 40063000 end; 40064000 FirstTime := false; 40065000 end; 40066000 40067000 Len := 6 * UPDATE_INFO [UI_RECSZ_WORDS]; 40068000 pRec := pointer (UserRec); 40069000 40070000 case UPDATE_INFO [UI_UPDATE_TYPE] of 40071000 begin 40072000 DBV_CREATE: 40073000 DBV_DELETE: 40074000 DBV_MODIFY: 40075000 replace pRec by pRec for Len 40076000 with Encryption; 40077000 else: 40078000 end; 40079000 40080000 Encrypt := Callback (pRec, Len, UPDATE_INFO, UserRec); 40081000 end Encrypt; 40082000 40083000 export Encrypt; 40084000 40085000 FirstTime := true; 40086000 freeze (temporary); 40087000 end. 40088000