API Interface to Expose Process

This section describes the method for creating Data Sources outside of the ODBC Expose Utility so that the expose functionality can be integrated into an existing application program or a customized front-end.

Setup

• Control Information

  The API requires the control information that is normally defined during the execution of the ODBC Expose Utility through Control File Maintenance, to be defined prior to execution. This includes the following information:

Element Name	Description	Single-Tier Defaults	Multiple-Tier Defaults
CONTROL-KEY	Control record key. This is always ‘CTL’	‘CTL’	‘CTL’
WORK-FILE-DIRECTORY	Directory number for the Expose Utility data files	Directory containing IDDBD	Directory containing IDDBD
DN-DESC	Flag to determine whether to use Data Element names or Data Element Descriptions	‘Y’	‘Y’

The data file ODDCTLPR has been defined to hold this information. This file contains the fields described above and can be accessed using the link odLCTLPR. Use either single- or multi-record maintenance to populate this data. All fields are mandatory. If this file is missing, the default values, listed above, will be used. Invalid information will result in API execution termination.

• File Suffixes

  In order for the required file suffix information to be used during the Expose process, the file ODDFSUFF must be populated. This file, accessible via the link odLFSUFF, contains three fields: The file suffix, the file suffix description and the use/no use flag. The file suffix and use/no use flag are required. During the Create (see C function in the Execution section) process, this file is read. Any file suffix records with a use/no use flag value of “Y” will be used to build expose records.

  

• Selected Link List

  This file, ODDLKSLT, contains a list of links to be used in place of the entire library. It is accessible from the link odLLKSLT. If this file is found, the records contained therein will be used during the C and U functions. The file contains two fields: The Link Name and a use/no use flag. Only the records containing a use/no use flag value of “Y” will be used to build expose records.

  

The file may contain links from one or more libraries.

Without this file present on the system, the expose process will default to the list of all links defined in the library specified in API$[2]. Only the links that fit the Expose Criteria will be exposed. Refer to the section titled Error Messages, Conditions section.

• Table Name

  By default, the resultant Table Name is derived from the Link Name. Alternatively, the Table Name can be configured by entering a value into the Server Table Name field in the Dictionary-IV Link Header. Note that only the first 17 characters will be used.

Execution

The following describes the syntax and parameters that need to be initialized for calling the API.

Syntax:

CALL “ODAPI”,API$[ALL]

Parameters:

API$[0] - Execution Status

. - Execution successful
### - Error value (See the section titled Security.)

API$[1] - Function:

C - Create New DSN specified in API$[3]. If API$[2] is blank,
uses list from ODDLKSLT and File suffixes from
ODDFSUFF.
U - Update DSN specified in API$[3]. If API$[4] is blank, uses
list from ODDLKSLT and File Suffix from API$[5]
D - Delete Link from DSN. Uses link(s) from API$[4].
G - Generate DSN specified in API$[3].
X - Delete DSN specified in API$[3].

API$[2] - Library

The 2-character name of the Dictionary-IV library that contains the links to expose.

API$[3] - DSN Name

A string value up to 32 characters in length.

API$[4] - Link Name for Update, Delete

May contain one or more links. A comma separates multiple links.

API$[5] - File Suffix

Used in conjunction with the D and U functions. No file suffix specification is necessary for the C function. Values will be derived from the ODDFSUFF file.

It is advised that API$[0] be checked following each call to the API to verify that the process completed successfully. In addition, the log file ‘tsexp.log’ should be reviewed. This file will contain details about changes that were made to elements, tables, and sorts during the expose process. It will also list any links that were not exposed and the reasons.

Example Usage

• Create a new DSN

Option 1 - Creates a DSN called TESTDSN

Option 2 - Creates a DSN called TESTDSN.

with all valid links from the UT library.

In this case the file ODDLKSLT must contain the list of links to be exposed.

API$[1]=”C”,

API$[1]=”C”,

API$[2]=”UT”,

API$[2]=””,

API$[3]=”TESTDSN”,

API$[3]=”TESTDSN”,

API$[4]=””,

API$[4]=””,

API$[5]=””

API$[5]=””

• Update a DSN

Option 1 - Updates a DSN called TESTDSN

Option 2 - Updates the DSN called TESTDSN

for links UTCUST and UTSALHSH.

with all links from the ODDLKSLT file.

API$[1]=”U”,

API$[1]=”U”,

API$[2]=””,

API$[2]=””,

API$[3]=”TESTDSN”,

API$[3]=”TESTDSN”,

API$[4]=”UTCUST,UTSALHSH”,

API$[4]=””,

API$[5]=””

API$[5]=””

Option 3 -

Updates a DSN called TESTDSN

for link UTLHELPT using File Suffix DEM

API$[1]=”U”,
API$[2]=””,
API$[3]=”TESTDSN”,
API$[4]=”UTLHELPT”,
API$[5]=”DEM”

• Delete Link from DSN

Deletes links UTCUST and UTSALHSH from the DSN TESTDSN.

API$[1]=”D”,
API$[2]=””,
API$[3]=”TESTDSN”, API$[4]=”UTCUST,UTSALHSH”, API$[5]=””

• Generate DSN

Generates the DSN called TESTDSN and produces the UDD.

API$[1]=”G”,
API$[2]=””,
API$[3]=”TESTDSN”,
API$[4]=””,
API$[5]=””

• Delete DSN

Deletes the DSN called TESTDSN.

API$[1]=”X”,
API$[2]=””,
API$[3]=”TESTDSN”,
API$[4]=””,
API$[5]=””

Errors

The following is a listing of the error values that may be returned in API$[0]:

101 -

Cannot access the DSN master, ODDDSNNM.

102 - Cannot find key “CTL” in Control File.
103 - Cannot read from the DSN master, ODDDSNNM.

110 - No hierarchical directory defined in the IPL file.
111 - No system directory Environment variable set (Windows error only).
112 -	Cannot access file TSODBC.INI.
113 -	Invalid function value in API$[1].
114 -	Occurs when there is no Selected Link file (ODDLKSLT) and no library is set in API$[2].
115 -	No DSN specified in API$[3].
116 -	No Link specified in API$[4].

From the TS ODBC DataServer Reference, version 8.9.1. Open this page in the PDF