Introduction

The ODB++2GBR translator is supplied as a library. The API for the library is shown below.

openODB

This call is used to initialize the library. It is mandatory and is always the first call made when using the library. This function also makes several checks to insure that the ODB++ structure is valid by checking for the presence of the matrix folder/file, step folders and layer folders.

int ACS_openODB
    (char * odbName, char * workingDir, struct ODB_InputParam * odbInitPtr);

Arguments

odbName

name of the odb file/structure (the library can read a compressed tgz file or if a path name is supplied this is assumed to be the top of the job directory hierarchy)

workingDir

If not NULL and 'workingDir' is a valid path this will be set as the working directory; if NULL or invalid, the working dir will be set to the value of the TEMP, TMP or TMPDIR environment variable (whichever is found first in their respective order); if the working_dir cannot be set, this function will fail.

odbInitPtr

this is a reserved param; its elements are:

  ExecPath: the executable path
  argc:number of additional arguments
  argv:list of additional arguments.


The possible additional args are:

  -dbg turns on additional debug data recorded to the log file
  -keep_tmpfiles keeps intermmediate files instead of cleaning them up upon closing
  -thrnum:<thrnum_int_val> sets the max number of concurrent threads

Return Values

0=successful; 1=fail

getODBOutputDir

Returns the path of the output directory.

char * ACS_getODBWorkingDir();

Return Values

string containing the path of the output directory

null if fail

getODBWorkingDir

This is used to determine what the library considers to be the working directory. Note that the working directory is often specified when opening the library; however it is allowable not to specify the working dir when opening the library and in such a case one would want to know where the library considers its working dir to be located.

char * ACS_getODBWorkingDir();

Return Values

string containing the path of the working directory

null if fail

getODBLastErr

This function is used to get the most recent error generated by the library. The callling program would do this in order to display an error message for the end user or to take some sort of action when an error is encountered.

char * ACS_getODBLastErr(int * errCode);

Arguments

Returns

the last error message and its associated error code

NULL if there is none.

getODBStepCount

Used to find out the number of "steppings" present in the ODB++ file.

int ACS_getODBStepCount();

Returns

the number of steps in the ODB or -1 if it failed

getODBStepInfoList

a detailed list of the steps present in the ODB++ file; stepList[0] will be set to the first array element in stepList; stepCount will be set to the number of steps in stepList

int ACS_getODBStepInfoList
    (ODB_StepInfo ** stepList, int * stepCount);

Arguments

ODB_StepInfo - data structure containing the step information

Returns

0=successful; 1=fail

stepList must be freed after it is no longer needed

getODBStepName

Returns the name of the step when provided with the step's index.

char * ACS_getODBStepName(int stepIdx);

Return

Either the step's name or NULL if the call fails.

getODBStepindex

Returns the index of the step when provided with the step's name.

int ACS_getODBStepindex(char * stepName);

Returns

the step's index in stepList or -1 if the call fails

getODBStepNameExtent

Used to determine the data extents of a named step. Calculates the Xmin,Xmax,Ymin and Ymax of the step's layout data. This call computes the extents by going through all data and layers in referenced by the step. It does not rely on the step' profile as it is possible to write ODB++ step without the profile information.

int ACS_getODBStepNameExtent
    (char * stepName, double * extent);

Arguments

stepName - the name of the step that the calling program wishes to obtain data extents

extent - Xmin, Xmax, Ymin and Ymax coordinates.

Return

0=success; 1=fail

getODBStepIdxExtent

Used to determine the data extents of a step by providing its index number (instead of its name). Calculates the Xmin,Xmax,Ymin and Ymax of the step's layout data.

int ACS_getODBStepIdxExtent
   (int stepIdx, double * extent);

Arguments

stepIdx - the index ID of the step that the calling program wishes to obtain data extents

extent - Xmin, Xmax, Ymin and Ymax coordinates.

Return

0=success; 1=fail

getODBStepNameProfileExtent

This call examine's the step's profile (which is one or more polygons) and generates the extents from that information. It appears that not all steps have a profile so this call should be used carefully. However if the profile is present the amount of computation using this call should be much faster than the calls that run through the entire database to calculate the data extents.

int ACS_getODBStepNameProfileExtent
    (char * stepName, double * extent);

Arguments

stepName - the name of the step for which the calling program wishes to obtain data extents

extent - Xmin, Xmax, Ymin and Ymax coordinates.

Return

0=success; 1=fail

getODBStepIdxProfileExtent

This call examine's the step's profile (which is one or more polygons) and generates the extents from that information. It appears that not all steps have a profile so this call should be used carefully. However if the profile is present the amount of computation using this call should be much faster than the calls that run through the entire database to calculate the data extents.

int ACS_getODBStepIdxProfileExtent
        (int stepIdx, double * extent);

Arguments

stepIdx - the index ID of the step for which the calling program wishes to obtain data extents

extent - Xmin, Xmax, Ymin and Ymax coordinates.

Return

0=success; 1=fail

getODBLayerCount

Use to determine the number of layers in this ODB++ file.

int ACS_getODBLayerCount();

Returns:

the number of layers in the ODB

getODBLayerInfoList

Use to obtain a list of layers and the number of layers in the ODB++ database.

int ACS_getODBLayerInfoList
    (struct ODB_LayerInfo ** layerList, int * layerCount);

Arguments

ODB_LayerInfo - the data structure to contain the layer information

layerList - the list of layers

layerCount - number of layers

Returns

0=success; 1=fail

layerList[0] will be set to the first array element in layerList

layerCount will be set to the number of layers in layerList

The data structure layerList should be freed after it is no longer needed

getODBLayerName

Returns the name of the specified layer.

char * ACS_getODBLayerName(int layerIdx);

Arguments

layerIdx - layer's index in layerList (starts with 0)

the layer name or NULL if it failed

getODBLayerIndex

Returns the index of the specified layer

int ACS_getODBLayerIndex(char * layerName);

Arguments

layerIdx - layer's index in layerList (starts with 0)

Returns

the layer's index in layerList or -1 if it failed

getODBExtent

Used to find the extents of a combination of step and layer. Since a step may have many layers, requesting the overall extents may give a much larger value than a particular step/layer combination. Note that before using this call, the calling program has already used getODBStepName to obtain the names of steps in the file as well as getODBLayerInfoList

int ACS_getODBExtent
         (char * stepName, char * layerName, double * extent);

Arguments

stepName - the name of the step for which the calling program wishes to obtain data extents

layerName - the layer used to calculate data extents. Only geometries on this layer will be used to calculate extents

extents - the data structure that will hold the extents information.

Returns

0=success; 1=fail

extent will be set to layer's extent value (minx,miny,maxx,maxy)

getODBLayerFirstDrawable

Returns the first drawable of the specified step/layer combination.

int 
ACS_getODBLayerFirstDrawable
(char * stepName, char * layerName, struct ODB_Drawable * drawable, int * type);

Arguments

stepName - the name of the step to evaluate

layerName - the name of the layer to evaluate

drawable - data structure holding the "features" coordinates and parameters

type - type of feature

Returns

-1=Fail
 1=ODB_Line
 2=ODB_Pad
 3=ODB_Arc
 4=ODB_Surface
 5=ODB_Text
 6=ODB_Barcode
 32767=ODB_LastDraw

getODBLayerNextDrawable

Returns the next drawable (getODBFirstLayerDraw must be called first).

int ACS_getODBLayerNextDrawable
        (ODB_Drawable * struct drawable, int * type);

Arguments

drawable - data structure holding the "features" coordinates and parameters

type - type of feature

Returns

-1=Fail
 1=ODB_Line
 2=ODB_Pad
 3=ODB_Arc
 4=ODB_Surface
 5=ODB_Text
 6=ODB_Barcode
 32767=ODB_LastDraw

getODBSymbolInfoList

Returns a list of all the user defined symbols in the ODB.

int ACS_getODBSymbolInfoList
         (struct ODB_SymbolInfo ** symbolList, int * symbolCount);

Arguments

ODB_SymbolInfo - data structure containing

symbolList

symbolCount - integer holding the number of symbols in the list

Returns

0=success

1=failure

symbolList[0] will be set to the first array element in symbolList

symbolCount will be set to the number of symbols in symbolList

NOTE

symbolList must be freed after it is no longer needed

getODBSymbolFirstDrawable

Returns the first drawable of the specified symbol. Note that the coordinates are "flattened" - any transformations in the step header are taken into account first.

int 
ACS_getODBSymbolFirstDrawable
(char * symbolName, struct ODB_Drawable * drawable, int * type);

Return:

0 if successful and 1 if failed

drawable will be set to NULL if it failed or to the first 
drawable of the specified symbol

drawable must be used immediately

type will be set to the type of drawable:
Failed              -1
ODB_Line            1
ODB_Pad             2
ODB_Arc             3
ODB_Surface         4
ODB_Text            5
ODB_Barcode         6
ODB_LastDraw        32767   *this drawable will be blank

getODBSymbolNextDrawable

getODBSymbolNextDrawable - Returns the next drawable (getODBFirstSymbolDraw must be called first).

int ACS_getODBSymbolNextDrawable
    (struct ODB_Drawable * drawableable, int * type);

Return

0=success; 1=fail

drawable will be set to NULL if it failed or to the  
next drawable of the previously specified symbol

drawable must be used immediately
type will be set to the type of drawable:

 Failed             -1
 ODB_Line            1
 ODB_Pad             2
 ODB_Arc             3
 ODB_Surface         4
 ODB_Text            5
 ODB_Barcode         6
 ODB_LastDraw        32767  *this drawable will be blank

getODBDcodes

getODBDcodes - Returns a list of all dcodes including the dcodes in the wheels specification and the synthesized ones.

int ACS_getODBDcodeList
   (struct  ODB_Dcode ** dcodeList, int * dcodeCount);

Return

0=success; 1=fail

dcodeList[0] will be set to the first array element in dcodeList
dcodeCount will be set to the number of dcodes in dcodeList

NOTE: dcodeList must be freed after it is no longer needed

getODBWheel

getODBWheel - Returns a list of all dcodes included in the wheels specification.

Return: 0=success; 1=fail

int ACS_getODBWheel(struct ODB_Dcode ** dcodeList, int * dcodeCount);

dcodeList[0] will be set to the first array element in dcodeList
dcodeCount will be set to the number of dcodes in dcodeList

printODBTree

Returns a string of the ODB info for the specified step/layerlist combination.

char * ACS_printODBTree
     (char * stepName, char ** layerList, int layernum, int traverse);

where

stepName - step's name
layerList - list of layer names
layerNum - number of Layers
traverse - 1=traverse the step-repeat, 0=don't traverse

Name/Rule Combinations

if stepName!=NULL && layer!=NULL
returns info of the specified step/layerlist combination

if stepName!=NULL && layer==NULL
returns info of the specified step and all its layers

if stepName==NULL && layer==NULL
returns info of the whole ODB (all combination)

if stepName==NULL && layer!=NULL
returns an error

Return: 0=success; 1= fail

getODBInfo

Returns the ODB info for the specified step/layerlist combination.

int ACS_getODBInfo
    (char * stepName, char * layerList[],   
        int layernum, struct  ODB_StepInfo * stepInfo);

Arguments

stepName - step's name
layerList - list of layer names

Step/Layer Combinations

if stepName!=NULL && layer!=NULL
returns info of the specified step/layerlist combination

if stepName!=NULL && layer==NULL
returns info of the specified step and all its layers

if stepName==NULL && layer==NULL
returns info of the whole ODB (all combination)

if stepName==NULL && layer!=NULL
returns an error

Return:

0=success; 1= fail

stepInfo will be set to the ODB_StepInfo of the specified step

stepInfo will contain step_index, extent, profile extent and a list of ODB_LayerInfo (as specified).

each layerInfo in stepInfo will contain layer_name, layer_index, context, type, extent, polarity, startname, endname, addtype, color

convertODBInput

Converts the ODB and creates a file for each of the step/layerlist combination.

int ACS_convertODBInput
    (char * stepName, char ** layerList, int layernum, 
                      char * outputName, int argc, char ** argv);

Arguments

stepName step's name

layerList list of layer names

outputName output path and filename

If no full path, output will be placed in the working directory; if there are several output layers, then the layer name and number will be appended to the output.

argc number of additional arguments

argv list of additional arguments. The possible additional args are:

  -unit:<inch or mm> set the unit of conversion

  -scale:<scale_dbl_val> set the scale of conversion

  -arcres:<res_dbl_val> set the arcres of conversion

  -arcsag:<sag_dbl_val> set the arcsag of conversion

  -odb_symbols keep the user defined symbols as a macro

  -step_repeat enable step repeat command in Gerber output

Step/Layer Combinations

if stepName!=NULL && layer!=NULL
converts the specified step/layerlist combination

if stepName!=NULL && layer==NULL
converts the specified step and all its layers

if stepName==NULL && layer==NULL
converts the whole ODB (all combination)

if stepName==NULL && layer!=NULL
returns an error

Return:

0=success; 1= fail

closeODB

closeODB - Closes the ODB internal database and cleans up.

int ACS_closeODB();

Returns

0=success; 1= fail