Section - 3 : PDF417 Rules

The PDF417 software for Documaker includes these section level rules:

CreateNYAAMVAData
CreatePDF417Barcode
GetNYAAMVAVar

The first rule lets you create the data while the second rule lets you create the bar code. These processes are separate to enhance performance. The third rule lets you retrieve members of the AAMVA structure after it is built. See Turning on Tracing on page 50 for debugging information.

In most cases, you will need to call the CreateNYAAMVAData rule only once in order to populate the AAMVA structure and copy it to the GVM variable. You can then call the CreatePDF417Barcode rule once for each bar code that you need to create. If you need to retrieve members from the AAMVA structure after it is populated, you can then call the GetNYAAMVAVar rule.

The screen shot below shows an example of using all three of these rules.

The CreateNYAAMVA rule is called once to populate the AAMVA structure and store it in the GVM named BARCODEVAR.
The CreatePDF417Barcode rule is called three times (to create three different bar codes), each time using the data stored in the GVM variable named BARCODEVAR.
The GetNYAAMVAVar rule is called once. It retrieves the ICOVERAGESTARTDATE member of the AAMVA structure and copies its value to the field named CSDATE, copies the RNAMEASONE1 member to the field named NAMEA1, and also copies the RNAMEASONE1 member to the GVM named NMA1.

Note: The NY AAMVA driver ID card application must store encrypted binary data into a PDF417 bar code. The standard Documaker method of mapping data from a data source to a variable field will not work in this case because the data is binary and not plain text. The rules and functions described here are designed to provide a method of creating the binary buffer needed and then inserting the data into the PDF417 bar code.

Note: This alternate approach works by using the Documaker technique known as GVM (Global Variable in Memory). A GVM symbol is a symbolically named dynamic memory buffer. The CreateNYAAMVAData rule creates the data buffer and attaches it to a GVM symbol. The other rules and functions reference the GVM data buffer by its symbolic name. You can use the PDF417 bar code object with rules such as the Move_it rule in other applications, but the NY driver ID card application must use the GVM approach described here.

CreateNYAAMVAData

To receive this rule, you must:

Be authorized to produce auto insurance policies in the state of New York.
Have executed the non-disclosure agreement with New York.
Have licensed Documaker technology from Oracle.

The CreateNYAAMVAData rule uses application and encryption routines provided by the state of New York for purposes of porting or including into custom applications.

Syntax

;CreateNYAAMVAData; GVMOutputVariable , CheckForRequired , INS_Key;

Parameters

Parameter	Description
GVMOutputVariable	Specifies the name for the GVM variable that will contain the 570 bytes of formatted data be stored into a PDF417 bar code by a later call. You can make several calls using this data to create bar codes of different sizes and locations, but which contain the same data. Keep in mind that this rule is typically run once, while you can call the CreatePDF417Barcode rule several times using the same source GVM data.
CheckForRequired	The New York application defines a number of variable data elements to be included in the bar code. Some of these elements are required. This parameter lets you decide when and to what extent to check for these required data elements. If you enter one (1), if any required fields are missing from the data, an error is issued for each missing field. If you enter two (2), if any required fields are missing from the data, a warning is issued for each missing field. If you enter three (3), processing continues and no errors or warnings are issued if required fields are missing. The default is 3. Other INI options control whether the Rules Processor continues processing or stops on errors and warnings. These options are documented in the Documaker Administration Guide.
INS_Key	Each insurance company that writes auto insurance for drivers in New York will receive a unique key signature. This value is an armored hex string. This parameter specifies that key. If you omit this parameter, you must include this information in the INI file. For security reasons, you may want to have the source code to this rule customized to hardcode the constant key value into the rule. The base version does not provide this option. If you use the INI file to provide the information, specify the value as shown here:
PassPhrase (implicit parameter)	The INS_KEY parameter is an armored 36-character hex string value. Internally, it must be de-armored using a pass phrase before it can be used. The rule does not support pass phrase as an explicit rule parameter, but the pass phrase is an implicit parameter necessary for compliance, and it must be specified in the INI file. The PassPhrase is a plain text message string that can only be obtained by an authorized insurance company from the NYSID. For security reasons, you may want to have the source code to the rule customized to hardcode the constant pass phrase string value into the rule. The base version does not provide this option. Specify the pass phrase value in the INI file as follows:

The rule begins by finding and destroying any existing GVM variable named by the GVMOutputVariable parameter.

The rule provides an interface between the Documaker batch process and application logic developed and provided by the NYSID. To interface with the New York application code, an interface structure must be filled out. This definition of this internal structure is specified by the New York application, and is called InsuranceInfo in C, and Oracle provides a COBOL version known as NYID-INSURANCE-INFO.

The rule automates the process of moving data within the Rules Processor into the proper position in the interface structure. The rule uses an internal table of variable names and has the necessary offsets and lengths to assemble the structure. The internal table also has flags to indicate which fields are required.
The rule checks each field in the table. The rule first looks in the INI file to see if you have specified alternate mapping. The rule uses the name as the option and looks in the INI file. If found, it examines the value to see if you specified cross-mapping. You can specify a variable field, a constant value, a GVM variable, a DAL variable, a DAL script, or any other existing built-in INI function. If there is no INI entry for the variable, the rule assumes the name will be used as is and it then looks for a field with that name.

The rule first looks for a variable field with a given name on the current section (FAP file). If the field is found on the section, that field will be used. If the field does not have any data or is blank, then the matching structure element will also be blank.

If the field is not found on the section, the rule next searches the entire document set for an occurrence of that named field which contains data. If no occurrence of the field can be found with data, the rule looks for a GVM variable with that name. If still no data is found, the rule looks for a DAL variable with that name. If it does not find a DAL variable, the search ends and no data will be used.

If an appropriate value is found, the rule uses the offset and length stored in the table to move the data into the interface structure. If no data was found, the corresponding structure member is left blank.

If the structure member is empty (blank), the rule examines the CheckForRequired parameter to see what action should be taken.

If the CheckForRequired parameter is	Then
1 and the data is empty	An error is issued
2	A warning is issued
3	No warning or error is issued

If an error is issued, other INI options for the Rules Processor determine whether processing continues or stops.

Once the InsuranceInfo structure has been assembled, the structure is passed in to the New York application API, along with the INS_Key parameter, the PassPhrase option, and the output structure, which is called InsuranceAAMVA.
The InsuranceAAMVA output structure contains 570 bytes of formatted data to be encoded into the bar code. The rule stores this formatted data in a GVM variable, named by the GVMOutputVariable parameter, for later use.

INI Options

The easiest implementation is one that provides the required data elements using the reserved names assigned by Oracle. These names are also used as C structure names in the New York application. Below, for convenience, a table provides a cross-reference of these names to COBOL structure member names used by other Oracle Insurance applications.

Many implementations will have some data elements available under different names. Some data elements require manipulation before being included into the bar code. To avoid requiring an existing form to be re-implemented or changes to the extract file, you may want to map the reserved variable names to other names or other sources of data.

This rule supports a number of INI options and ways to configure each of the 30 or so variables that are necessary to feed the New York structure to alternate sources.

< NYAAMVA >

RLastName1 = field name

RFirstName1 = ;constant value

RMiddleName1 = ;

RNameSuffix1 = ;

RNameAsOne1 = ;

RClientId1 = ;~(any existing INI built-in)

RLastName2 =

RFirstName2 =

RMiddleName2 =

RNameSuffix2 =

RNameAsOne2 =

RClientId2 =

RStreet =

RCity =

RState =

RZipCode =

ROrganizationLine1 =

ROrganizationLine2 =

ROrganziationFein =

VVinNumber =

VYear =

VMake =

VRepInd =

VHistInd =

VTowInd =

VSeats =

IIssuerId =

IInsCompanyCode =

IInsIssuanceDate =

ICoverageStartDate =

ICoverageEndDate =

IPolicyNumber =

Using the INI mapping options

The INI file offers many ways to get the necessary interface variables. Here are some examples:

< NYAAMVA >

RLastName1 = LAST NAME

The above example looks for data named LAST NAME. The rule first looks for a field on this section. Then it looks for a global field. Next, it looks for a GVM variable. Finally, it looks for a DAL variable.

VTowInd = ;N

The above example shows how a company that never insures tow trucks could short cut this part and hardcode a constant N as the tow truck indicator value.

This table shows all of the variables accessed via the table, the corresponding C-structure member name, and whether the variable is required.

NYID-INSURANCE-INFO name Used by the COBOL copy book record structure.	Corresponding NY InsuranceInfo C-structure member name and INI option.	Required?
NYID-R-LAST-NAME-1	RLastName1	Yes
NYID-R-FIRST-NAME-1	RFirstName1	Yes
NYID-R-MIDDLE-NAME-1	RMiddleName1	No
NYID-R-NAME-SUFFIX-1	RNameSuffix1	No
NYID-R-NAME-AS-ONE-1	RNameAsOne1	Yes
NYID-R-CLIENT-ID-1	RClientId1	Yes
NYID-R-LAST-NAME-2	RLastName2	No
NYID-R-FIRST-NAME-2	RFirstName2	No
NYID-R-MIDDLE-NAME-2	RMiddleName2	No
NYID-R-NAME-SUFFIX-2	RNameSuffix2	No
NYID-R-NAME-AS-ONE-2	RNameAsOne2	No
NYID-R-CLIENT-ID-2	RClientId2	No
NYID-R-STREET	RStreet	Yes
NYID-R-CITY	RCity	Yes
NYID-R-STATE	RState	Yes
NYID-R-ZIP-CODE	RZipCode	Yes
NYID-R-ORGANIZATION-LINE-1	ROrganizationLine1	Yes
NYID-R-ORGANIZATION-LINE-2	ROrganizationLine2	No
NYID-R-ORGANIZATION-FEIN	ROrganizationFEIN	Yes
NYID-V-VIN-NUMBER	VVinNumber	Yes
NYID-V-YEAR	VYear	Yes
NYID-V-MAKE	VMake	Yes
NYID-V-REP-IND	VRepInd	Yes
NYID-V-HIST-IND	VHistInd	No
NYID-V-TOW-IND	VTowInd	No
NYID-V-SEATS	VSeats	No
NYID-I-ISSUER-ID	IIssuerID	Yes
NYID-I-INS-COMPANY-CODE	IInsCompanyCode	Yes
NYID-I-INS-ISSUANCE-DATE	IInsIssuanceDate	Yes
NYID-I-COVERAGE-START-DATE	ICoverageStartDate	Yes
NYID-I-COVERAGE-END-DATE	ICoverageEndDate	Yes
NYID-I-POLICY-NUMBER	IPolicyNumber	Yes

CreatePDF417Barcode

Use this rule to create a PDF417 bar code.

Syntax

;CreatePDF417Barcode;N=BarCodeName,F=FontID,E=ECCLevel,G=GVMSourceVariable,T=TopFAPCoord,L=LeftFAPCoord,B=BottomFAPCoord, R=RightFAPCoord,W=Warning;

Parameter	Description
BarCodeName	Specifies a name for the bar code. This name typically is the name of the associated PDF417 bar code variable field object located on the current section. Older implementations that do not have a bar code object may specify the name of an associated box object located on the current section, and if there is no box object the name is still required to provide the root name used by a series of dynamic text labels that contain the bar code text data.
FontID	Specifies the PDF417 font you want to use for this instance of the bar code. This parameter is optional if you specified the name of an associated PDF417 variable data field, in which case the object already specifies the font to be used. You can choose between two sizes of PDF417 bar codes fonts: 9 dots high by 12 dots wide and 12 dots high by 16 dots wide. While Oracle does not mandate the IDs you can use, it does provide an FXR file which contains the attributes for the two fonts. The IDs for these fonts are: 912 and 1216. For more information on the included FXR files, see PDF417 FXR Files.
ECCLevel	Specifies the degree of error correction to be used in the bar code. This parameter is optional if you specified the name of an associated PDF417 variable data field, in which case the object already specifies the ECCLevel value to be used. The range is from zero (0) to eight (8). The default is four (4), which is the value recommended by the NYSID. For more information, see Sizing a PDF417 Bar Code.
GVMSourceVariable	Specifies the name of a GVM variable which contains the data to be embedded into the bar code. The CreateNYAAMVAData rule must have previously created this data and stored it in this GVM variable. The New York application currently specifies 570 bytes of data. It is likely that you will need to use the same source data to create a bar code multiple times on the same page, or on multiple forms in the form set. The bar codes can be different sizes and use different fonts yet contain the same source data. This is why it is important for performance that data creation and bar code creation steps are performed by separate rules.
TopFAPCoord LeftFAPCoord BottomFAPCoord RightFAPCoord	Each bar code instance must specify a location and a rectangular size. You can specify this information from... A named PDF417 bar code variable field object on the FAP file A named box object on the FAP file Explicit rectangle FAP coordinates The rectangle coordinate parameters are optional if you specified the name of an associated PDF417 bar code variable field, in which case the object already specifies the coordinates. When included, the coordinates explicitly provide the dimensions of the rectangular area to contain the bar code. If you omit the rectangle parameters, the system gets the coordinates from either the associated variable bar code field or box object.
Warning	If the system cannot locate the specified bar code or box for the rule and the section is a multi-page section, you will get a warning. To suppress this warning, set this parameter to No (W=No). The default is Yes.

Note: Do not specify a location and a rectangular size using explicit rectangle coordinates in a multi-page section. This causes the system to create the bar code on every page of the multi-page section.

This rule performs these actions:

The rule first checks for a bar code variable field object with the specified name. If found, this field provides the coordinates, font, and error correction level.
This rule was originally introduced before the system supported PDF417 as a built-in bar code object type and therefore alternate methods of specifying the bar code location and parameters had to be provided. If this is an implementation from a prior version of the product, there may not be a bar code variable field object configured for use on the section. In this case the rest of the steps are applicable.
The rule first checks to see if the rectangle coordinates were provided. The most important ones specify the bottom and right. If the bottom or right coordinates are zero or blank. the system assumes the coordinates are provided by a box object. The box object must be on the same section and must have the name specified in the BarCodeName parameter.
The rule uses the rectangle coordinates that were specified explicitly or specified by the named box. Using these coordinates, the rule determines the height and width of the bar code.
The rule uses the font specified in the FontID parameter to locate the requested bar code font. The FXR font information provides the cell height, width, and baseline values.
The rule uses the font cell width to calculate the number of text characters (COLS) that can fit within the width of the bar code rectangle.
The rule uses the cell height to calculate the number of text character text labels (ROWS) that can fit within the height of the bar code rectangle.
The rule checks for and destroys any existing bar code text. These text labels will be internally named with a root name matching the name specified by BarCodeName.
The rule retrieves the bar code data from a GVM variable specified by the GVMSourceVariable parameter.
The rules passes the bar code data, along with the calculated number of rows and columns, and the requested error correction level, to internal APIs that create the text characters necessary to render the bar code.

An error at this point could mean that the bar code area was too small for the source data and ECC level.
The rule creates dynamic text labels, row by row, for all of the returned bar code text. Each dynamic text label will have a root name specified by the BarCodeName parameter, the font specified by the FontID parameter, and its cell parameters, data length specified by COLS, and will contain the text for that row.

The dynamic text labels are unloaded automatically into the NAFILE.DAT file.

GetNYAAMVAVar

Use this rule to retrieve members of the AAMVA structure after it is built. Certain fields in the AAMVA structure that are not supplied by the user are resolved during the processing of the CreateNYAAMVAData rule. This rule lets you retrieve the data from those fields and place it in a field or a GVM variable.

Note: The field must exist before this rule is executed. You can create a field using the MK_Hard rule on the field. You cannot create an empty field.

Syntax

;GetNYAAMVAVar;GVMOutputVariable,AAMVAMember, Field/GVMVariable;

You can retrieve more than one AAMVA data member in a single call to GetNYAAMVAVar. To do this, simply use another pair of AAMVAMEMBER and FIELD/GVMVARIABLE combinations.

Parameter	Description
GVMOutputVariable	This is the name of the GVM variable supplied to CreateNYAAMVAData where the AAMVA structure is stored.
AAMVAMember	This is the name of the AAMVA field you want to retrieve. It should match the names used in the INI file, such as RNameAsOne1, RLastName2, and so on.
Field/GVMVariable	This is where the data will be placed. If you are sending the data to a field, must use the F switch, and for GVM variables use the V switch.

Example

;GetNYAAMVAVar;G=CustomerInfo,RNameAsOne1,F=FULLNAMEFIELD, RLastName2,V=SECONDNAME;

In this example, the rule gets the RNameAsOne1 data from the CustomerInfo AAMVA data and places it in the field FULLNAMEFIELD. It will also get the RLastName2 data member and place it in the GVM variable SECONDNAME.