Help For Rexx Interface to DirectTalk Databases

Though the information shown here refers to DirectTalk for Windows, it is applicable to the OS/2 version as well.

Installation

  1. Unzip the contents of the file to the same directory as where DirectTalk is installed. This help file can be deleted. Only the DLL is needed:
    REXX2DT2.DLL -- OS/2
    REXXDTNT.DLL -- Windows


Usage

To use the Rexx Interface, you must first register the functions to Rexx in your Rexx program.

For the Windows NT version:

call RxFuncAdd 'DTNTDBLoadFuncs', 'REXXDTNT', 'DTNTDBLoadFuncs'
call DTNTDBLoadFuncs

For the OS/2 version:

call RxFuncAdd 'DT2TDBLoadFuncs', 'REXX2DT2', 'DT2DBLoadFuncs'
call DT2DBLoadFuncs

Please refer to the Object Rexx documentation for more information.

Function Summary

Important: The names of the function for OS/2 are the same as shown here, except they start with DT2. For example, DTNTDBLoadFuncs in the OS/2 version is called DT2DBLoadFuncs.


DTNTDBLoadFuncs -- Makes all functions in this DLL known to REXX so REXX programs may call them.

DTNTDBDropFuncs -- Drops all functions in this DLL from REXX.

DTNTOpenSession -- Opens a session to the specified DirectTalk system. Returns the session id which is required by all other functions. This must be the first function performed after loading the functions with DTNTDBLoadFuncs.

DTNTCloseSession -- Closes the session with the DirectTalk General Server. This should be called after completing all work with DirectTalk before exiting the REXX program.

DTNTCreateDB -- Creates a new DirectTalk database.

DTNTCloseDB -- Closes a DirectTalk database after it has been opened for read or write.

DTNTDeleteRecord -- Deletes a specified record from a DirectTalk database.

DTNTGetRecord
-- Reads a record from a DirectTalk database.

DTNTSearchRecord -- Search a DirectTalk database for the record with key that matchs search criteria.

DTNTUpdateRecord -- Adds a new record or updates an existing record in a DirectTalk database.

DTNTGetPath -- Obtains the exact location path for where DirectTalk is storing its databases.

DTNTGetStats -- Obtains pertinent information about specified DirectTalk database

Why are some of parms shown in quotes below?

When Rexx passes data to a user written DLL, like the Rexx Interface to DirectTalk databases, it nicely resolves any variables and passes the contents or value of the variable to the function. Since several of these functions have parameters that are output parameters (ie. the function is going to place data in or update the value of a variable), the function must know the name of the variable itself. By putting the variable name in quotes, Rexx will pass the variable name to the function instead of the variable's value.

If you miss putting quotes around one of the output parameters, you may find that in a program loop, the function will work the first time it is called but fail all other times. If you use a variable that has never been initialized (perhaps because you're expecting the function to do it), Rexx automatically initializes it to the name of the variable in upper case. Therefore, the function sees the correct data (the variable name) the first time it is called. The next time, the function gets the contents of the variable, instead of the name. If the variable content happens to be the name of another variable in your program...

If, reading the above, did nothing but confuse you - just remember:

"If the parameter is one that the function will update, it must be the name of a variable in quotes!" 

Function Details

Function: DTNTDBLoadFuncs 

Syntax: call DTNTDBLoadFuncs quiet 

Parms: quiet - any value to shut off load messages from displaying

Return: null string 

Return to top of this page

Return to the main page.

Function: DTNTDBDropFuncs 

Syntax: call DTNTDBDropFuncs 

Parms: None 

Return: null string 

Return to top of this page

Return to the main page.

Function: DTNTOpenSession 


Syntax: rc = DTNTOpenSession('ses_var', server, rw_mode, adapter, timeout) 

Parms: 

ses_var = name of variable where function will place session handle returned from OpnSesDAE() or OpnSesDA() 
 server = name of the DirectTalk node to connect to
rw_mode = 'READONLY' - Only read operations will be allowed or  'READWRITE' - Both read and write operations will be allowed.
adapter = Specify 255 if DirectTalk is running standalone. Specify 0, 1, 2, or 3, for the LAN adapter being used  when system is running as node in a network. On OS/2, the adapter is typically 0. On Windows, the adapter is typically 1.
timeout = time, in seconds, to wait for response from DirectTalk server. Maximum is 127. Specify 0 for indefinite wait.

Return: 

return code from OpnSesDAE() or OpnSesDA() function call, OR
-1 invalid parameter specified for rw_mode
-2 invalid parameter specified for adapter
-3 unable to save session id in ses_var

Return to top of this page

Return to the main page.

Function: DTNTCloseSession 

Syntax: rc = DTNTCloseSession(session_id) 

Parms: session_id = session id for session returned from previous DTNTOpenSession function. 

Return: return code from CloSesDA() function call

Return to top of this page

Return to the main page.

Function: DTNTCreateDB 

Syntax: rc = DTNTCreateDB(session, filename, key, record,) 

Parms: 

session = variable containing session ID returned from DTNTOpenSession 
filename = name of the DirectTalk database to create. Do not  specify a path!
key = length of the key. Must be between 1 and 49
record = length of the record. Must be between 1 and 4096 

Return: 

return code from CreateDA() function call, or
-1 value in key invalid 
-2 value in filename not valid FAT file name

Return to top of this page

Return to the main page.

Function: DTNTCloseDB 

Syntax: rc = DTNTCloseDB(session, filename) 

Parms: 

session = variable containing session ID returned from DTNTOpenSession
filename = name of the DirectTalk database to close. Do not specify a path!

Return: 

return code from ClsFilDA() function call, or
-1 value in filename not valid FAT file name

Return to top of this page

Return to the main page.

Function: DTNTDeleteRecord 

Syntax: rc = DTNTDeleteRecord(session, filename, key) 

Parms: 

session = variable containing session ID returned from DTNTOpenSession 
filename = name of the DirectTalk database
key = key for record to be deleted

Return: 

return code from PutRecDA() function call, or
-1 value in filename not a valid FAT file name

Return to top of this page

Return to the main page.

Function: DTNTGetRecord 

Syntax: rc = DTNTGetRecord(session, filename, key, 'record') 

Parms: 

session = variable containing session ID returned from DTNTOpenSession
filename = name of the DirectTalk database
key = key for record
record = name of variable where function is to put record data

Return: 

return code from GetKeyDA() or GetStats() function call, or
-1 value in filename not a valid FAT file name
-2 unable to allocate memory to hold record data 
-3 unable to save data in record variable

Return to top of this page

Return to the main page.

Function: DTNTSearchRecord 

Syntax: rc = DTNTSearchRecord(session, filename, seachkey, search, 'key_found', 'record_found') 

Parms: 

session = variable containing session ID returned from DTNTOpenSession
filename = name of the DirectTalk database
searchkey = initial search key
search = one of the following searches
'='  -- equal to
'>'  -- greater than
'<'  -- less than
'>=' -- greater than or equal to
'<=' -- less than or equal to
key_found = name of variable where matching key is stored
record_found = name of variable where record data for key_found is stored 

Return: 

return code from GetKeyDA() or GetStats() function call, or
-1 invalid search parameter
-2 value in filename not a valid FAT file name
-3 unable to save data in record variable 

Return to top of this page

Return to the main page.

Function: DTNTUpdateRecord 

Syntax: rc = DTNTUpdateRecord(session, filename, key, record, record_len) 

Parms: 

session = variable containing session ID returned from DTNTOpenSession
filename = name of the DirectTalk database
key = key of record to add or update
record = record data for associated key to be stored
record_len = length of record data

Return: 

return code from PutRecDA() or GetStats() function call, or
-1 value in filename not a valid FAT file name
-2 record length longer than database record length
-3 key length longer than database key length

Return to top of this page

Return to the main page.

Function: DTNTGetStats 

Syntax: rc = DTNTGetStats(session, filename, 'stats') 

Parms: 

session = variable containing session ID returned from DTNTOpenSession
filename = name of the DirectTalk database
stats = name of the variable where function stores the database statistics. Data is a series of numbers that can be separated using PARSE VALUE. Information is returned in the following order:
  1. Record Size (bytes)
  2. Key Size (bytes)
  3. Index block size (bytes)
  4. Number of records in database
  5. Number of keys in database
  6. Number of index blocks in database
  7. Total size of database (bytes)
  8. Maximum number of I/O operations to find a record
  9. Maximum number of I/O operations to add a record
  10. Maximum number of I/O operations to delete a record

Return: 

return code from GetStats() function call, or
-1 value in filename not a valid FAT file name

Return to top of this page

Return to the main page.

Function: DTNTGetPath 

Syntax: rc = DTNTGetStats(session, 'path') 

Parms: 

session = variable containing session ID returned from DTNTOpenSession
path = name of the variable where function stores the path location where DirectTalk databases are kept.

Return: return code from GetPathDA() function call

Return to top of this page

Return to the main page.