Importing/exporting .ddl files in DBC Finance and DBC Debt Manager

A .ddl file is an ASCII text file that can be created using any text editor or by a custom program. It contains information formatted using the DDL specification to define a bond issue for a DBC programs -- including DBC Finance, DBC Debt Manager and DBC Housing. Each program has specific behavior; there are several features that require research, testing and documentation. However, this document will generally focus on the bond, reserve fund and expense information that can be imported and exported by DBC Finance in Debt/Size. DBC Debt Manager does not import/export any reserve fund or expense information.

The .ddl file must be formatted strictly according to the definitions below. Each group of data is always preceded by a line containing a keyword that clearly describes what is on the upcoming line(s). Each line that contains a keyword begins either with two slash characters (//) or two pound characters (##).

The order in which the data and keywords appear in a .ddl file is significant. Subsequent keywords can override the information contained in earlier parts of the .ddl file. Thus it is important to process a .ddl file completely from beginning to end.

Extra spaces at the beginning of each line are not significant. In the examples in this document, the data at deeper levels have been indented to make them clearer on the printed page. However, a program reading .ddl files cannot assume the presence or absence of leading spaces on any given line, while a program generating .ddl files can insert as many spaces at the beginning of any line as it sees fit.

Any line that begins with four slash characters //// signifies that it is a comment line and should be ignored when importing a .ddl file. Note that comments must span the entire line, so that a sequence of four slashes in the middle of a line does not mean that the remainder of the line is a comment.

Except for tables, every keyword occurs on a line by itself. Data associated with the keyword should be on the next line. Data (or anything else) that incorrectly follows the keyword can result in bad data. For tables, the keyword should be followed by a space and the number of rows in the table.

Note:

The DDL syntax is case sensitive. And spelling counts.
The general principle of DDL is "garbage in, garbage out". The DDL import/export is not forgiving.
Undocumented behavior is not guaranteed to be supported in the future.

Importing data in DBC Finance

You may import one or more series from the same .ddl file.

If the issuer name and series name in the .ddl file corresponds to an existing issuer/series in the .df2 file, the series will be replaced with the information contained in the .ddl file. Any existing bond component, reserve fund or expense in the series with the same short name as a one in the .ddl file, will also be replaced.

To import a .ddl file into DBC Finance:

If importing into an existing .df2 file, make a backup of the .df2 file.
In DBC Finance, open or create the .df2 file which will save the imported .ddl file.
Close any open documents.
Goto Tools | Import Data | Import DDL File.
Select the .ddl file.
An hourglass will appear while DBC Finance is importing the .ddl file.
A popup message will indicate when DBC Finance has finished.

Unless otherwise indicated, all imported data is treated as protected data, as if entered by hand. Any assumed default values or settings are not protected.

To import a specific reserve fund deposit or expense amount, indicate the amount in the NLF.

Importing only bond data in DBC Finance

You may update the bond data for only one series from a .ddl file. The .ddl file may contain data (including non-bond data) for multiple series.

If the issuer name and series name in the .ddl file corresponds to an existing issuer/series in the .df2 file, existing bonds with the same short name will be replaced with the information contained in the .ddl file. Existing bonds in the series with short names that do not appear in the .ddl file will remain in the series.

To import a .ddl file into DBC Finance:

If importing into an existing .df2 file, make a backup of the .df2 file.
In DBC Finance, open or create the .df2 file which will save the imported .ddl file.
Open the series which contain the bonds to be updated. It should be the currently active document.
Goto Tools | Import Data | Import Bonds (DDL).
Select the .ddl file.
An hourglass will appear while DBC Finance is importing the .ddl file.
A popup message will indicate when DBC Finance has finished.

Unless otherwise indicated, all imported data is treated as protected data, as if entered by hand. Any assumed default values or settings are not protected.

To import a specific reserve fund deposit or expense amount, indicate the amount in the NLF.

Exporting data in DBC Finance

You may export one or more series from the same .df2 file.

To export multiple series to a single .ddl file from DBC Finance:

In DBC Finance, open the .df2 containing series to export.
Close all documents.
Go to Tools | Export Data | Export DDL File.
The Export Multiple Series to DDL File dialog will appear. Note, only series with a status of Actual or Actual Refunding are selectable/exportable.
Click on the folder to list individual series under the issuer.
To select an item to export, check the box corresponding to the issuer or series to export.
Hit Export when the selections are complete.
Specify the name and location of the .ddl file to export.
If the .ddl file exists, specify a different .ddl file or confirm the overwrite.

To export a currently open series (the status of the series is irrelevant):

If desired, perform the calculation or solution involving the series.
Go to Tools | Export Data | Export DDL File.
Specify the name and location of the .ddl file to export.
If the .ddl file exists, specify a different .ddl file or confirm the overwrite.

Importing data in DBC Debt Manager

You may import one or more series from the same .ddl file.

The import assumes any issuer/series (i.e. //Issuer and //Series) combination in the .ddl file does not exist in the database. Importing a .ddl file as a method for updating the database may produce expected results.

To import a .ddl file into DBC Debt Manager:

Make a backup of the database.
When starting DBC Debt Manager, select the ODBC datasource that will contain the imported .ddl file.
Goto Tools | Import | DDL.
Specify the Issuing Authority and the .ddl file.
An hourglass will appear while DBC Debt Manager is importing the .ddl file.
A popup message will indicate when DBC Debt Manager has finished.

Exporting data in DBC Debt Manager

You may export one or more series from the same Issuing Authority to a single .ddl file.

To export series from DBC Debt Manager:

When starting DBC Debt Manager, select the ODBC datasource containing the series to export.
Goto Tools | Export | DDL.
Specify the issuer/series to export.
Specify the .ddl file.
It is beyond the scope of this document to describe all the prompts on the Export Series screen. Refer to Help in DBC Debt Manager.
Hit OK when the selections are complete.
If the .ddl file exists, it will be overwritten.

DBC Data Language (DDL) Specification

Revision number 2012.1, 10/25/2012

The first line in a .ddl file will always contain the keyword //$DDL followed by the DDL revision number. For example:

//$DDL 2012.1

At the top level, there are keywords available to define global parameters, to cause certain actions to occur and to initiate/end subgroups or tables. Each subgroup can have its own set of keywords to define parameters, cause actions, and even create subgroups or tables of its own. Therefore it is possible to have a recursive definition for subgroups.

The possible data types in a .ddl file are:

string - Characters that must be enclosed in quotes. For example, "this" is a string.
number - A numeric value. 5.0 is imported/exported as 5. 5% is imported/exported as .05. For numbers entered in thousands (e.g. maturity amounts), 5.000 is exported as 5000.
date - A date formatted as mm/dd/yy, mm/dd/yyyy or yyyymmdd. If a date is not indicated, it is generally assumed to be aligned to the fiscal date.
table - One or more rows of data containing a fixed number of comma separated items which are strings, numbers or dates.
NLF - One or more rows containing NLF. NLF should appear as it would if you entered it manually. NLF should not be quoted. The import/export does not resolve incorrect NLF syntax. The NLF syntax is beyond the scope of this document, refer to Help in DBC Finance.
basis - An interest day count basis. If a basis is not indicated, it is generally assumed to be 30/360. Specify (quotes are optional):

"30/360" - 30/30 basis "ACT/ACT" - ACT/ACT basis

"ACT/360" - ACT/360 basis "ACT/365" - ACT/365 basis

freq - An interest payment/compounding frequency. If a frequency is not indicated, it is generally assumed to be semiannual. Specify (quotes are optional):

"12" - annual	"-7" - weekly, note the dash
"6" - semiannual	"-14" - biweekly, note the dash
"3" - quarterly	"-28" - 28 days, note the dash
"2" - bimonthly	"-35" - 35 days, note the dash
"1" - monthly

callable_dates - Indicate whether bonds are callable on any date or only interest payment dates. See //BeginCallTable. Specify (quotes are optional):
"any" - bonds are callable on any date (default)
"int_date" - bonds are only callable on interest payment dates

DDL series definition

The following table describes the DDL syntax to create/update a series. The name/description and status correspond to the short/long name and status used to create issuers and series in DBC Finance. The dated/delivery date and interest payment information corresponds to data you would enter on the Debt/Size Assumptions screen.

Note: There is no shortcut to define information that carries over from one series definition to the next. For example, the first interest date should be stated for each series even if all series in the .ddl file should be saved under the same issuer.

DDL Keyword (data)

//NewSeries
Indicates the start of series information. Everything after this line, up to the next //NewSeries line or the end of the file, is used to define a series

//Issuer (string)
The issuer name (short name) up to 8 characters using A - Z, 0 - 9 and the underscore character.

//IssuerTitle (string)
The issuer description (long name) up to 50 characters.

//Series (string)
The series name (short name) up to 8 characters using A - Z, 0 - 9 and the underscore character.

//SeriesTitle (string)
The series description (long name) up to 50 characters.

//SeriesStatus (string)
The series status. The currently supported statuses are:

"Act" - an actual new money series.
"ActRef" - an actual refunding series.
"Prp" - a proposed new money series.
"PrpRef" - a proposed refunding series.
"Templt" - a template series.
DBC Debt Manager considers all series to be actual (new money or refunding) series. There is no such concept as "proposed" or "template"

//Dated (date)
The dated date.

//Deliv (date)
The delivery date.

//FirstInt (date)
The first interest payment date.

//IntFreq (number)

The interest frequency. If //IntFreq is omitted, semiannual is assumed.

DBC Debt Manager does not import this data but will use it as the default for bond components. DBC Debt Manager does not export this data.

//Basis (basis)

The interest day basis. If //Basis is omitted, 30/360 is assumed.

DBC Debt Manager does not import this data but will use it as the default for bond components. DBC Debt Manager does not export this data.

Sample series definition

The following .ddl fragment represents the beginning of a series definition. //NewSeries, //Issuer, //IssuerTitle, //Series, //SeriesTitle, //SeriesStatus should be the first 6 keywords to define a series.

//NewSeries
//Issuer
"ABC"
//IssuerTitle
"ABC County"
//Series
"2010A"
//SeriesTitle
"Series 2010A"
//SeriesStatus
"Act"
//Dated
01/01/2010
//Deliv
01/15/2010
//FirstInt
07/01/2010

DDL bond definition

The following table describes the DDL syntax to create/update a bond component. The dated/delivery date and interest payment information is optional and corresponds to data you would enter on the Bond Component screen. For the bond component, this information overrides the information on the Debt/Size Assumptions screen as it would if you manually entered the information.

Note: An existing bond component in the series (.df2 file) with the same name as the bond component in the .ddl file will be updated.

DDL Keyword (data)

//BeginBondDescription
Indicates the beginning of a bond component subgroup.

//EndBondDescription
Indicates the end of a bond component subgroup.

//Name (string)
The bond component name (short name) up to 8 characters using A - Z, 0 - 9 and the underscore character.

//Title (string)
The bond component description up to 50 characters.

//Options (string)
One or more optional characteristics of the bond component:

"CAB" - a capital appreciation bond.
"Term" - a term bond with sinking funds.
"Serial" - a serial bond.
"Note" - a note bond.
"ConvCAB" - a convertible CAB bond.

Each option must be quoted. All options must appear on a single line separated by a comma.

To denote a serial CAB bond, the options would be:

"CAB","Serial"
or
"Serial","CAB"

//Dated (date)
The dated date. If omitted, the series information is assumed. In DBC Debt Manager, this field is not imported/exported.

//Deliv (date)
The delivery date. If omitted, the series information is assumed. In DBC Debt Manager, this field only applies to CABs and convertible CABs.

//FirstInt (date)

The first interest payment date. If omitted, the series information is assumed.

In DBC Finance, this field does not apply to CABs and convertible CABs.

In DBC Debt Manager, this field only applies to CABs and convertible CABs.

//IntFreq (freq)
The interest payment frequency. If //IntFreq is omitted, the series information or semiannual is assumed.

//Basis (basis)
The interest day basis. If //Basis is omitted, 30/360 is assumed.

//MaturityDenom (number)

For CABs or convertible CABS, the future value of the bond at maturity.

In DBC Finance, if omitted, 5000 is assumed.

In DBC Debt Manager, if omitted, 0 is assumed.

//FinalCompoundingDate (date)
For convertible CABS, the final compounding date for the bond.

//BDA_int_only (bda)

//BDA_pandi (bda)

Any change to the interest payment date or principal and interest payment date (maturity date) if it falls on a non-business date (weekend or holiday).

If //BDA_int_only is omitted, no business day adjustment is assumed.
If //BDA_pandi is ommitted, then interest payment date options is assumed.
Business day adjustment:

"bda_accruednext" - accrued and paid on the next business day.
"bda_paidnext" - paid on the next business day.
"bda_accruedpre" - accrued and paid on the previous business day.
"bda_paidpre" - paid on the previous business day.
"bda_accrued2biz" - accrued and paid on the next business day that is followed by a business day.

//BeginMaturityTable rows (table)

Indicates the beginning of a bond maturity table and the number of rows in the table. Each entry (row) in the table must have 6 items of data separated by commas.

The fixed columns, corresponding to the Maturity Structure tab, are:

maturity date
par amount - 5000 = $5000
interest rate - .01 = .01%
yield - .01 = 1%
price - 100 = par
takedown - 5 = $5

Example:

$90000 maturing on 1/1/2015, paying 5%, yielding 4.95%, sold at 101 with a $2 takedown would be defined as:

1/1/2015,90000,.05,.0495,101,2

Items may be left blank (e.g. yield, takedown), such as:

//// yield and takedown are blank 1/1/2015,90000,.05,,101,

The optional keywords are:

//Denom= - the issuance bond denomination.
In DBC Finance, the default is $5,000. For CABs and convertible CABs, if the denomination is omitted, a default value will be calculated based on the maturity denomination.

In DBC Debt Manager, if the no value is provided, the default is 0.

//CallDate= - the call date for the bond.
//CallPrice= - the call price for the bond.
//PPUDate= - the PPU date for the bond.
This field is not supported in DBC Debt Manager.

//UnrefundAdv= - the amount to be excluded from an advanced refunding analysis.
//Variant= - the variant name for the bond in quotes.
This field is not supported in DBC Debt Manager.

//CUSIP= - the CUSIP for the maturity.

Multiple keywords and values must be separated by a space.

To define the 1/1/2015 maturity with a $10000 denomination, variant name "AMT" and CUSIP name "XYZ":

1/1/2015,90000,.05,.0495,101,2 //Denom=10000 //Variant="AMT" //CUSIP="XYZ"

//EndMaturityTable

Indicates the end the bond maturity table.

//BeginCallTable rows callable_dates lag (table)

Begin definition of a table containing call dates/prices. After //BeginCallTable, specify:

rows - the number of rows in the table
callable_dates - type of callable dates (optional, default is "any")
lag - number of days advance notice before the call (optional, default is 0)

Each entry in the table has 2 columns separated by a comma. The columns are:

call date - rows arranged from earliest date to latest date
call price - 100 denotes a par call

//EndCallTable
End the bond call table.

Sample bond component

//BeginBondDescription, //Name and //Title should be the first 3 keywords used to define a bond.

The following .ddl fragment can define a CAB term bond that is only callable on interest payment (compounding) dates. The values for dated date, delivery date and first interest payment (compounding date) will be defaulted from the series level.

/BeginBondDescription
//Name
"TERM25"
//Title
"2025 Term bonds"
//Options
"Term"
//BDA_int_only
"bda_accruednext"
//MaturityDenom
5000
//BeginMaturityTable 5
    01/01/2026,11962,0.05,0.05,100,0 //Denom=1196.2
    01/01/2027,11962,0.05,0.05,100,0 //Denom=1196.2
    01/01/2028,11962,0.05,0.05,100,0 //Denom=1196.2
    01/01/2029,11962,0.05,0.05,100,0 //Denom=1196.2
    01/01/2030,11962,0.05,0.05,100,0 //Denom=1196.2
//EndMaturityTable
//BeginCallTable 3 int_only
  01/01/2014,102
  01/01/2015,101
  01/01/2016,100
//EndCallTable
//EndBondDescription

Obsolete method for defining CABs and Convertible CABs

Previous versions of DDL assumed all CABs compounded to $5,000. A CAB that compounded to $10,000 could not be defined. For example:

//// CAB assumed to compound to 5000
//Options
"Serial","CAB"

Previous versions of DDL allowed convertible CABs specified with optional parameters.

A convertible CAB with the future value and final compounding date defined:

//// convertible CAB compounds to 10000 on 1/1/2010
//Options
"Serial","ConvCAB 01/01/2010 10000"

A convertible CAB with only the final compounding date defined (a future value of $5,000 is assumed):

//// convertible CAB assumed to compound to 5000 on 1/1/2010
//Options
"Serial","ConvCAB 01/01/2010"

A convertible CAB with only the future value ($5,000) assumed:

//// convertible CAB assumed to compound to $5,000 on an unspecified date
//Options
"Serial","ConvCAB"

New method for defining CABs and Convertible CABs

The current version of DDL allows the future value and/or final compounding date to be defined explicitly.

A CAB can be defined as:

//// CAB compounds to 10000
//Options
"Serial","CAB"
//MaturityDenom
10000

A convertible CAB can be defined as:

//// convertible CAB compounds to 10000 on 1/1/2010
//Options
"Serial","ConvCAB"
//MaturityDenom
10000
//FinalCompoundingDate
01/01/2010

Rate, Price, Yield

Blank items will be unprotected. The row must still contain 6 items. The 1/1/2021 maturity with no stated yield or takedown would be defined as:

1/1/2021,100000,.12,,100,

Protected values (DBC Finance only)

The order for protecting the rate, yield and price, whether blank or not, is:

If the rate is not blank then protect the rate.
If the price is not par then protect the price.
If the yield is not blank and the rate is not protected then protect the yield.
If the yield is not blank, the price is not protected and the yield does not equal the rate then protect the yield.

In general, if the rate, price and yield are specified, the yield will be ignored, unprotected and calculated.

DDL DSRF / CapI fund definition (DBC Finance only)

The following table describes the DDL syntax to create/update a debt service reserve fund or capitalized interest fund.

Note: An existing reserve fund in the series (.df2 file) with the same name as the reserve fund in the .ddl file will be updated.

If a calculation or solution was performed, the .ddl file will state the calculated reserve fund deposit or expense amount (as a use of funds).

DDL Keyword (data)

//BeginReserveDescription
Indicates the beginning of a DSRF/CapI fund subgroup.

//EndReserveDescription
Indicates the end of a DSRF/CapI fund subgroup.

//Name (string)
The DSRF/CapI fund name (short name) up to 8 characters using A - Z, 0 - 9 and the underscore character.

//Title (string)
The DSRF/CapI fund description (long name) up to 50 characters.

//Options (string)
Indicate whether the reserve fund is a DSRF or CapI fund. This must come before the NLF. The choices are:

"DSRF" - the NLF applies to the balance requirement.
"CapInt" - the NLF applies to the draw requirement.
If no option is indicated, DSRF is assumed. The option should be stated before using the //BeginCalcMethod keyword.

//Amount (number)

After performing a calculation or solution involving the series, this amount indicates the deposit to the fund (as per Sources & Uses).

The //Amount keyword is only used for exports. To import a specific amount use NLF.

//BeginCalcMethod rows
Indicates the beginning of a DSRF/CapI fund NLF and the number of rows in the formula. The //Options keyword should have previously indicated whether for NLF is a balance requirement or a draw requirement. Each row of NLF must appear on separate lines as if it would be entered manually in DBC Finance.

//EndCalcMethod
Indicates the end of the NLF.

//Funding
Indicates the funding option for the fund. The options are:

"PV" - the fund is net funded using the stated rate.
"GIC" - the fund is net funded using the stated rate, first interest payment date, frequency, day basis.
"GROSS" - the fund is gross funded using the stated rate, first interest payment date, frequency, day basis.

//Rate (number or string)
Indicates the investment interest rate for the fund. A number indicates Investment Interest Rate is Specified percent. A string (i.e. "ARBYIELD") indicates Investment Interest Rate is Arbitrage yield. "Arbitrage yield" is a choice, the actual arbitrage yield is not imported or exported.

//FirstInt (date)
The first interest payment date for the fund. Does not apply to a net funded (PV) fund.

//IntFreq (freq)
The interest payment frequency for the fund. Does not apply to a net funded (PV) fund. If no frequency is indicated, semiannual is assumed.

//Basis (basis)
The interest day basis for the fund. Does not apply to a net funded (PV) fund. If //Basis is omitted, 30/360 is assumed.

//ApplyDrawsToDS (string)
Determines the state for Apply draws for debt service box:

"1" - checked
"0" - not checked
If //ApplyDrawsToDS is omitted, checked is assumed.

Sample DSRF component

//BeginReserveDescription, //Name, //Title and //Options should be the first 4 keywords used to define a reserve fund.

The following .ddl fragment can define a DSRF based on the 3 prong test. Note the NLF is not enclosed in quotes. The number of lines in the formula must be stated after //BeginCalcMethod. Any acceptable manually typed NLF shorthand (e.g. "ds" for "Debt Service") can also be used in the .ddl file.

//BeginReserveDescription
//Name
"DSRF"
//Title
"Debt Service Reserve Fund"
// Options
"DSRF"
//Rate
"ARBYIELD"
//BeginCalcMethod 4
  Lesser of
  10% of Reasonable Par Amount
  Maximum annual Debt Service
  125% of average annual adjusted Debt Service
//EndCalcMethod
//Funding
"PV"
//EndReserveDescription

DDL expense definition (DBC Finance only)

The following table describes the DDL syntax to create/update an expense.

Note: An existing expense in the series (.df2 file) with the same name as the expense in the .ddl file will be updated.

The Type of Expense must be Other, using a different option may produce errors on import or export.

DDL Keyword (data)

//BeginExpenseDescription
Indicates the beginning of an expense subgroup.

//EndExpenseDescription
Indicates the end of an expense subgroup.

//Name (string)
The expense name (short name) up to 8 characters using A - Z, 0 - 9 and the underscore character.

//Title (string)
The expense description (long name) up to 50 characters.

//Type (string)
The expense type corresponding to the simpler Type of Expense options on the Expense Description tab:

"UD" - Underwriters Discount
"COI" - Cost of Issuance
"OTHER" - Other
If no expense type is indicated, Other is assumed. The other options for Type of Expense are not exported/imported.

//Options (string)
If an option appears, it indicates the corresponding box in the Expense Description tab is checked. The options are:

"ARB" - Include in Arbitrage Yield. Note the options on the detail button are not exported/imported.
"TIC" - Include in TIC.
"ALLIN" - Include in All-In TIC.
"NIC" - Include in NIC.
"2PCT" - Include in 2% limit.
"SOLUTION" - Include in bond optimization.

The options must be appear on a single line separated by a comma.

When creating an expense in DBC Finance, the Include in All-In TIC box is checked by default. When importing a .ddl file, the above boxes (including Include in All-In TIC) are assumed to be not checked unless the option is used. In other words, when creating the expense manually in DBC Finance, Include in All-In TIC will be checked by default, but the import does not have the "ALLIN" option as a default.

//Amount (number)
After performing a calculation or solution involving the series, this amount indicates the expense (as per Sources & Uses). The Type of Expense must be Other. This is a calculated amount. If the expense is a fixed amount, use NLF.

//BeginCalcMethod rows (NLF)
Indicates the beginning of an expense NLF and the number of rows in the formula. Each row of NLF must appear on separate lines as if it would be entered manually.

//EndCalcMethod
Indicates the end of the NLF.

Sample expense component

// BeginExpenseDescription, //Name and //Title should be the first 3 keywords used to define an expense.

The following .ddl fragment can define a bond insurance expense. Note the NLF is not enclosed in quotes. The number of lines in the formula must be stated after //BeginCalcMethod. Any acceptable manually typed NLF shorthand (e.g. "ds" for "Debt Service") can also be used in the .ddl file

//BeginExpenseDescription
//Name
"INS"
//Title
"Bond Insurance"
//Type
"OTHER"
//Options
"ARB","ALLIN"
//BeginCalcMethod 1
  1.000% of Total adjusted Debt Service
//EndCalcMethod
//EndExpenseDescription

Back to DBC Support page

"30/360" - 30/30 basis	"ACT/ACT" - ACT/ACT basis
"ACT/360" - ACT/360 basis	"ACT/365" - ACT/365 basis