Formatting Procedures
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.
Overview.
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 Files
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:
DATA/GENFORMAT/databasename/CONTROLwhere 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.
-
Save
DATA/GENFORMAT/databasename/CONTROL. -
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",
"databasename" ["logicaldatabasename"])Where Is "SUPPORT"The literal that represents the DBSupport program
The quotation marks are required."databasename"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:
OBJECT/DATABRIDGE/SUPPORT/databasename— or —
OBJECT/DATABRIDGE/SUPPORT/databasename/logicaldatabasenameThese data set-specific layout tables contain the offsets and sizes of individual data items.
Caution
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 "SYMBOL/DATABRIDGE/INTERFACE"or
$SET INCLUDE_ENGINE INCLUDE_SUPPORT
$INCLUDE "SYMBOL/DATABRIDGE/INTERFACE"Note
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.
Note
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