Library Functions

  Previous topic Next topic JavaScript is required for the print function Mail us feedback on this topic! Mail us feedback on this topic!  
Common parameters for following functions

<cServerIPorAddress>

A character string representing the name or IP address of the server where Caché Database is hosted. It can be one of the following formats:

127.0.0.1   [ localhost ]
www.vouch.info  [ Server on the Web ]
10.0.40.111  [ Server on Local Network ]

Please make sure that Caché Database is up and running on the said server before executing any of the connection commands.

 

<nPort>

A numeric representing the port number on which Caché Database Server is listening to client requests. This number is 1972 by default alloted by the server setup program when Caché Database is installed.

You will never need to change this default port configuration under normal circumstances, though however, you can do so if there is a valid reason to do so. Please refer to Caché reference material to know more about it.

 

cUsername

<cUserName>

A character string representing user name who is assigned to be connected to the database. On installation Caché creates one user name as _system having all the administrative rights.

You can use default user name or create multiple users with different roles/rights and assign one to the application. Please read the Caché documentation how to manage users.

From CachéRDD point of view a user must have read/write rights to the namespace application is logging to.

 

cPassword

<cPassword>

A character string representing valid password which is assigned to the <cUserName>. By default Caché assigns SYS as password to _system user at the time of installation.

 

nTimeout

<nTimeout>

Amount of time in seconds to wait for the connection to materialize. By default it is 30 seconds.

You should control this parameters through some .ini setting as it may be tweaked under certain circumstances. For all practical purposes default settings hold good.

 

cNamespace

<cNamespace>

A character string representing Namespace to connect to. In Caché, NAMESPACE is synonymous to DATABASE in other RDBMS dialects but differs in concept and approach.

One or multiple databses can be mapped to a single Namespace and hence eliminates the need to always point to a physical database which in turn enhances the maintainability of your applications. This parameter is mandatory and assumes no defaults.

A Namespace can not be more than 31 characters in length. For any practical purpose this is sufficient size.

 

hConnection

<hConnection>

CachéRDD generated numeric index of the array where information supplied with CachéSetServerParams() and CachéAddConnection(),  or CachéAddConnectionEx() is stored along with the Caché Database returned connection information.

hConnection can be obtained by one of the following three functions:

1.CachéAddConnection()
2.CachéAddConnectionEx()
3.CachéSetConnection()

and is supplied as the last parameter to all the subsequent functions contained in this library.

Please note that RDD funtions affected by hConnection are only DbUseArea() and DbCreate() and corresponding command set. All subsequent RDD calls retrieve this information from AREADATA structure. Thus:

USE ( cTable ) NEW SHARED VIA "CACHERDD" CONNECTION ( hConnection )

 

 

CacheSetServerParams ( cServerIPorAddress, nPort, cUsername, cPassword, nTimeout ) -> aOldParams

This functions sets the parameters to access the Caché Server and subsequent operations are based on these paarmeters. None of the parameters is taken as default. All are mandatory. The return value of this function is an array containing previous settings.

CacheAddConnection ( cNamespace ) -> hConnection

The function returns the connection handle if successful, otherwise 0. The returned connection handle is used for all subsequent Caché specific function. The most recent call to this function sets the current connection handle. To set another connection handle as current connection, CachéSetConnection() function must be called. If no connection handle is supplied to subsequent Caché specific functions, the current connection handle is used as default. Forr RDD methods this default is used while DbUseArea() and DbCreate() functions are called if no connection handle is passed to the function. All subsequent RDD methods will use connection handle established with work area at the time of opening the table.

Before calling this function, you need to issue CachéSetServerParams() as CachéAddConnection() fetches all other values off this function stack.

CacheAddConnectionEx ( cServerIPorAddress, nPort, cUserName, cPassWord, nTimeOut, cNameSpace ) -> hConnection

The function is a replacement to CachéSetServerParams() and CachéAddConnection() combined together. The return value is the handle to the connection established for <cNameSpace> on server <cServerIpOrAddress>. Please refer to CachéSetServerParams() and CachéAddConnection() for details about the parameters and return value.

CacheSetConnection ( hConnection ) -> hOldConnection

The function sets the current connection to <hConnection> which will be used by the subsequent Caché*() functions plus DbCreate() and DbUseArea() RDD functions. Typically this function is called when multiple connections are opened with CachéAddConnection() or CachéAddConnectionEx() functions. If only one connection is obtained, there is no need to call this function any time.

CacheCloseConnection ( hConnection ) -> lSuccess

The function closes the <hConnection> from the server and cleans up occupied stacks. Typically this function is called only when application has opened multiple connections and one/some is/are needed to be closed. This is not necessary to close a connection unless you need to free-up memory and a connection process. Application closes all the opened connections at the time of termination.

CacheGetConnectionInfo ( nInfo, hConnection ) -> cInfoString

The function returns <cInfoString> corresponding <nInfo> for [hConnection]. If <hConnection> is not supplied, current connection's info is returned.
 
<nInfo> is one of the following constants defined in CachéRDD.ch:

DBCI_CONXN

hConnection

DBCI_IP

cServerIP == 127.0.0.1     10.0.40.111     www.vouch.info

DBCI_PORT

nPort

DBCI_DATABASE

cNameSpace

DBCI_SCHEMA

SQLUSER

DBCI_CONXNSTRING

cServerIP+'['+cPort+']:'+cNameSpace

DBCI_USEEXCLUSIVE

0

Please use the #define constants to access this information as the values may change in the future releases of CachéRDD.

CacheSetSchema ( cSchema, hConnection ) -> cOldSchema

The function sets the default schema name for <hConnection> and returns the old schema name. To know about what SCHEMA means, its logistics, and how this is implemented in CachéRDD, click here...

<cSchema> A pure alpha character string without any punctuation characters. It defaults to 'SQLUSER', the default schema in Caché Database. Note that for normalization purposes it is always converted to uppercase.

CacheSetSchemaAsIs ( lNewSetting ) -> lOldSetting

The function returns logical setting if Schema name be kept as is supplied or convert to uppercase and optionally sets the new value. By default it returns false means always uppercase Schema name before submitting to the database alongwith table name.

CacheSetTableNameAsIs ( lSet ) -> lOldSetting

The function informs RDD if table name supplied as parameters to various functions be kept AS IS. By default table names are converted to UPPERCASE for normalization purposes.

NOTE: If you set this flag to TRUE, then you ALWAYS need to be sure that the table name you are supplying is the same. Caché naming conventions are case sensitive.

The function returns previos settings. The function is a global setting and is viisble in all connections. The following functions are affected by this setting:

DbCreate()
DbUseArea()
CachéExistTable()
CachéExistIndex()
CachéDropTable()
CachéDropIndex()

The above description holds good for CachéSetSchemaAsIs() too.

CacheGetCurrentProcessId ( hConnection ) -> nProcessId

The function returns the ProcessID of the <hConnection>. This process ID is given by OS. SO it can be viewed in Task Manager as one of the threads in the name of your application. Your application may have more than one process ids depending upon the number of connections you might have opened with CachéAddConnection() or CachéAddConnectionEx() functions.

CacheGetServerDate ( hConnection ) -> dServerDate

The function returns date of the server where Caché Database is running. The date is returned in the current date format set by Set( _DATE_FORMAT ).

<hConnection> defaults to
1) If call to USED() equals TRUE and RDDNAME() equals 'CACHERDD', the connection handle being used by current work area.
2) Otherwise current connection

This is assumed that this function may be used in data entry screens so the connection handle used defaults to current work area handle if one is available otherwise current connection handle.

CacheGetServerTime ( hConnection ) -> cServerTime

The function returns the time of the server where Caché Database is running in the format hh:mm:ss.

<hConnection> defaults to
1) If call to USED() equals TRUE and RDDNAME() equals 'CACHERDD', the connection handle being used by current work area.
2) Otherwise current connection

This is assumed that this function may be used in data entry screens so the connection handle used defaults to current work area handle if one is available otherwise current connection handle.

CacheSetLocks ( acLockString, hConnection ) -> lSuccess

The function returns SUCCESS or FAILURE all the locks in <acLockString> have been obtained for [hConnection].

<acLockString> A character string or a one-dimensional array of strings representing locks to be obtained. The failure and success depends upon the completness of locks, i.e., either all locks requested be obtained or none. Even if one lock request fails the functions returns failure.

The locks so obtained are local to the application. External processes never knows about these locks. Any operations done under this construct will respect the application commands only.

This function is useful in situations when you are absolutely sure that no external process is about to interfere with tables

Please note that external process is termed as a process which is not initiated by your application; like ODBC driven access to your tables, etc. Multiple instances of your application via multiple terminals are treated as same process for this locking mechanism as the same way as RLock() or FLock(). You can think of this lock mechanism in terms of non-workarea locks. These locks are STRINGID centered rather than RECNO or FILE oriented. I found a lot of situations where I can control business logic with this mechanism. For example, I obtain SEMAPHORES through this mechanism while I am about to update a lot of tables which require proper serialization. A real-time example would be out of the scope this documentation but still I will try to prove my point.

If the locks could not been released due to some error or otherwise, these are automatically released by the server once application instance goes out of scope, i.e., if application is done with or terminated in any situation.

CacheReleaseLocks ( acLockString, hConnection ) -> lSuccess

The function releases the locks contained as string ids in <acLockString> obtained via CachéSetLocks() function. The function returns failure or success of the operation. Please refer to CachéSetLocks() for details about its implementation.

<acLockString> A character string or a one-dimensional array of strings representing locks to be obtained. The failure and success depends upon the completness of locks, i.e., either all locks requested be obtained or none. Even if one lock request fails the functions returns failure.

Also make sure that [hConnection] refers to same connection supplied with CachéSetConnection(). Typically an application needs to release all locks thus obtained after the completion of action being executed in-between, buy you may release a partial list of locks instead of all locks obtained. That way you will be responsible to relese all remaining obtained locks.

CacheExistTable ( cTable, hConnection ) -> lExists

The function returns a logical to indicate if <cTable> do exist or not in the database represented by [hConnection].

<cTable> is the name of the table in the format : "cScema||cTableName". Please refere to article "Table Names & Schemas".

CacheDropTable ( cTable, hConnection ) -> lSuccess

The function returns success or failure if <cTable> in database represented by [hConnection] could been dropped/removed or not.

<cTable> is the name of the table in the format : "cSchema||cTableName". Please refere to article "Table Names & Schemas".

CacheExistIndex ( cTable, hConnection ) -> lExists

The function returns a logical to indicate if indexes for <cTable> do exist or not in the database represented by [hConnection].

<cTable> is the name of the table in the format : "cSchema||cTableName". Please refere to article "Table Names & Schemas".

CacheDropIndex ( cTable, hConnection ) -> lSuccess

The function returns success or failure if indexes of <cTable> in database represented by [hConnection] could been dropped/removed or not.

<cTable> is the name of the table in the format : "cSchema||cTableName". Please refere to article "Table Names & Schemas".

CacheExistIndexByTag( cTag ) -> lSuccess

The function returns whether index tag represented by <cTag> in the current work area exists or not. The function assumes that a table is open and is in use.

CacheTuneTable( cTable, hConnection ) -> NIL

The function tries to tune up that table represented by <cTable>. In Caché space 'tuning a table' refers to the selectivity pattern of different fields based on the current data. It may take some time to finish. The main purpose of tuning a table is to optimize and speed-up the SQL queries. As far as CachéRDD is concerned it has no effect unless you start to use its SQL interface where it will matter most.

CacheBeginTransaction ( hConnection ) -> lSuccess

The function returns the success or failure if transaction processing in database represented by [hConnection] could be started or not.

CacheEndTransaction ( hConnection ) -> lSuccess

The function returns the success or failure if transaction initiated by CachéBeginTransaction() in database represented by [hConnection] could be commited or not.

CacheRollBackTransaction ( hConnection ) ->lSuccess

The function returns the success or failure if a transaction initiated by CachéBeginTransaction() in database represented by [hConnection] could be rolled-back or not.

CacheTransactionLevel ( hConnection ) -> nCurrentTransactionLevel

The function returns the number as an integer of current transaction level if more than one transaction is initiated with CachéBeginTransaction() for the same [hConnection] as Caché provides a limited functionality of nested transactions. If no transaction is in progress it returns 0.

CacheInsertLockMode ( nMode, hConnection ) -> nPrevLockMode

The function set the locking mode to honour when appending/inserting a record for the database represented by [hConnection] and returns the previously set mode.

<nMode> CachéRDD supports three append locking modes, viz,;

1.INSERT_LOCK_MODE_CLIPPER - Unlock previously locked record and tries to lock the currently appended record.
2.INSERT_LOCK_MODE_ADVANTAGE - Retains the previously locked records and also locks the current appended record.
3.INSERT_LOCK_MODE_NOLOCK - Does not locks the current record and also does not unlock the previous records.

The default is INSERT_LOCK_MODE_CLIPPER. INSERT_LOCK_MODE_NOLOCK is important when you are to append a large number of records and you know there is no concurrency, i.e., during upload of existing tables to the server. This increases the performance of uploads manyfold.

Note that the function issued is per <hConnection>. So after this is called all database operations in all work areas respect these settings. Suggested practice is: call this function before APPEND FROM ... is executed and reset after APPEND FROM terminates so that other work areas are not affected.

CacheLockTimeout( nSeconds, hConnection ) -> nPreviousTime

The function attempts to set the time in seconds to finish a lock request and returns the previous setting. In Caché any lock request, be if a FLOCK or RLOCK, needs a specific time to timeout if lock cannot be obtained immediately. It is different than DBFCDX where attempt to lock a record returns immediately with success or failure flag.

By default this value is set to 2 seconds. You may experiment with larger/shorter period if you experience some weired behavior. In my in-production application this amount of time seems to be sufficient.

CacheFieldsFetchMode ( nWA, nMode ) -> nPrevFetchMode

The function sets the mode to retrieve the record/field values from the server. It returns the previous settings.

<nWA> The workarea handle obtained by Select() command. Because it is not a workarea method of the RDD, it is mandatory to supply this argument.

<nMode> The mode to retrieve data values from the server. This could be one of the following two modes:

1.CACHE_FIELDS_FETCH_MODE_RECORD - The default and per standards of other RDD's like DBFCDX.
2.CACHE_FIELDS_FETCH_MODE_FIELDS - To force CachéRDD to pull values from the server per field basis.

Both methods have merits and demerits. In per record basis, all the fields are read from the server just with first call to a field value request for a particular record. This makes application to make a single trip to the server for all fields but increases the transportation overload and network traffic. On the otherhand, in per field basis, only field value requested is fetched from the server thus reducing the transportation overload but increases the number of trips to the server corresponding to number of fields being fetched for a particular record. You need to experiment with both under different scenarios. In my experiments CACHE_FIELDS_FETCH_MODE_RECORD has proved to be faster, but I am sure I might not been able to test it all possibilities.

The function is depricated for now. CACHE_FIELDS_FETCH_MODE_RECORD is active currently. I was experimenting with such behavior and then found that on RDBMS levels it is always faster to make fewer trips to the server than transferring a larger data in one shot.

CacheStopJournal ( hConnection ) -> lSuccess

The function tries to stop the server-wide journal writing. Once the journal writing has been stopped no transactional control can occur. So this function has to be used with upmost care. Typically you may need to call this function when uploading your exiting tables to Caché via APPEND FROM... command and you are sure that no significant activity is being performed elsewhere. The call to this function prior to APPEND FROM.. reduces the upload time considerably. Once the job is over, you will have to call CachéStartJournal() to reverse the process.

Please note that there is no way to inform the database to start journalling automatically once it has been stopped. So your code is responsible to handle this request itself.

CacheStartJournal ( hConnection ) -> lSuccess

The function attempts to restart journalling by the Caché Server and returns its success or failure. Please refer to CachéStopJournal() for the functionality.

CacheGetTables ( cSchema, hConnection ) -> aTableNames

The function returns an one-dimensional array of character elements containing names of the tables present in <cSchema> of <hConnection>.

<cSchema> is the schema name, synonymous to folders in files-on-disk. Default is the Schema associated with the <hConnection>.

CacheGetProcesses ( hConnection ) -> aProcesses

The function returns a two-dimensional array of character elements containg following info:

PROCESS_NUMBER
PROCESS_EXE
PROCESS_IP
PROCESS_LINES
PROCESS_NODE
PROCESS_INTRANSACTION
PROCESS_NAMESPACE
PROCESS_OSUSERNAME
PROCESS_STATE
PROCESS_CACHEUSERNAME
PROCESS_USERINFO

The above constants can be found in CachéRDD.ch. All elements are of type Character. Each row in <aProcesses> represents a process on the server. All those processes whose PROCESS_EXE does not have .EXE signatures is excluded. System processes initiated by the Caché server itself are also excluded.

CacheGetProcessInfo ( nProcessID, hConnection ) -> aProcesses

The function returns a two-dimensional array ( but with one row only ) of character elements of process specific information for <nProcessID>. The structure of the column elements is as:

PROCESS_NUMBER PROCESS_EXE PROCESS_IP PROCESS_LINES PROCESS_NODE PROCESS_INTRANSACTION PROCESS_NAMESPACE PROCESS_OSUSERNAME PROCESS_STATE PROCESS_CACHEUSERNAME PROCESS_USERINFO

The above constants can be found in CachéRDD.ch.

<nProcessID> a numeric representation of process running on the server. Typically it represents a connection thread for a client. If more than one connections are opened by the client in a single application, these will be counted as many processes and will be allother separate IDs. For the application in context <nProcessID> can be obtained with CachéGetCurrentProcessID(). This parameter is mandatory.

CacheGotoPhantom( nWA ) -> TRUE

The function positions the record pointer to phantom record. This function provides a reliable way to provide phantom record very cruicial to some application. By RDD commands it is never possible to guarantee that record pointer will ever be positioned as requested no matter what sequence application applies. Typically in DBFCDX we do like :

GO LastRec()+1

or

GO BOTTOM; SKIP

In the first scenario you never know what is the state of the table in between GO and calculating LastRec()+1. Also the behavior of GOTO is different in CachéRDD, internally, though in normal execution of application you will not see any difference.

Similarly in the second case the moment GO BOTTOM returns and SKIP is executed some other process has appended new record.

CachéGotoPhantom() will ever allow you to fill memory variables with blank field values.

CacheIsRecLocked ( nWA, nRecNo ) -> lLocked

The function checks if <nRecNo> is locked by any process, external or RDD oriented, and returns its status TRUE or FALSE. Note that this is nor an RDD method so it is impractical to use it like - (MyTable)->CachéIsRecLocked(). Instead it has to be called directly with/without parameters.

<nWA> work-area number representing a table. Defaults to work-area returned by SELECT() function.

<nRecNo> record number whose lock status is queried. Defaults to number returned by RECNO() function.

CacheGetLockInfo ( nWA, nRecNo ) -> aProcesses

The function returns a two-dimensional array of character elements of information about the process holding lock on <nRecNo>. Pleease refer to CachéGetProcesses() function for the possible values of elements in <aProcesses>. <aProcesses> will contain only one row.

<nWA> work-area number representing a table. Defaults to work-area returned by SELECT() function.

<nRecNo> record number whose lock status is queried. Defaults to number returned by RECNO() function.

CacheGetAllLocks ( nWA ) -> aRecordsLocked

The function returns a one-dimensional array of record number which are currently locked by any process, external or RDD oriented, for <nWA>. Please note that it is not an RDD method so cannot be used as aliased expression.

<nWA> work-area number. Defaults to work-area returned by SELECT() function.

CacheRecallDeleted( nWA, nRecNo ) -> cState

The function attempts to put back previously deleted record represented by <nRecNo> in <nWA> and returns the state of operation as a character string. If it is "OK" then assume it has been successful otherwise read the status info.

Please refer to "Deleted Records" chapter for comprehensive information how deleted records are being managed in CachéRDD.

CacheSetUserInfo ( cInfo, hConnection ) -> lSuccess

The function sets the USER-INFO string on Caché stack which is returned as an array element of CachéGetProcesses(), CachéGetProcessInfo() and CachéGetLockInfo() and returns the previous stack information.

<cInfo> a character string maximum by 16 bytes

CacheGetVersionInfo ( hConnection ) -> aVersionInfo

The function returns the version information as a one-dimensional array of following structure:

1.Version Info String comprising detailed information -
Caché for Windows (Intel) 5.2 ( Build 329_0_4733 )....
2.Operating System - Windows/Unix
3.Plarform - Intel
4.Single User - 0 = FLASE 1=TRUE
CacheGetLicenseInfo ( hConnection ) -> aLicenseInfo

The function returns a one-diemensional array of following elements:

CacheGetInstallInfo ( hConnection ) -> aInstallInfo

The function returns a one-diemnsional array of installation folders:

CacheSetUseExclusive( nMode, hConnection ) -> nPrevMode

The function controls the behavior of USE ... EXCLUSIVE command. By default this command is implemented as per DBFCDX standards. Internally CachéRDD is managing this behavior via a special lock.

In production I encounted a peculiar problem with Caché when a large number of locks were causing a deadlock under certain situations. I refered the matter with Intersystems' support, who, after long tests and discussions, reached to the conclusion that the way CachéRDD is handling locks does not confirms to the SQL way of programming. And as Caché Database is SQL oriented by design, they cannot guarantee the smooth behavior under heavy locks scenario.

This necessitated me to devise another mechanism. But I also wanted to remain as close to DBFCDX as possible. Under network environment it is always suggested to use a table shared. As most of the tables are opened in shared mode, I decided to not use a shared lock at all. Instead I let the application open any table even if it has been used exclusive by another process. I could do so by applying a special FLOCK to simulate  USE ... EXCLUSIVE behavior. This way any other process using the same table in EXCLUSIVE mode was not allowed  though it was able to open the table in SHARED mode but was not allowed to make any updates to it.

This behavior is controlled through <nMode> parameter in above function, viz.,

nMode == 0 Default, as Clipper

nMode == 1 Treat Exclusive Use as Shared and apply FLock() to succeed

nMode == 2 Deny Exclusive Use and Raise an Error

So the tradeoff with <nMode> == 1 :

1.Two processes cannot open a table in EXCLUSIVE mode.
2.Only one process can open a table in EXCLUSIVE mode and all other processes can open in SHARED mode but cannot make any updates to it.

This function has to be called immediately after CachéAddConnection[Ex]() function. Also it should not be changed in rest of the code. Anyway, if you need exact DBFCDX behavior then do not call it all. However, suggested implementation is <nMode == 1> OR <nMode == 2> if you can live without opening a table in EXCLUSIVE mode.

I may remind you that EXCLUSIVE/SHARED mode has no effect on external processes if <nMode == 0>. But if <nMode == 1> then external processes will not be allowed to update it though they will be able to read its contents.

CacheGetCounter( cKeyword, hConnection ) -> nCounter

The function returns the next available incremented number associated with <cKeyword> which defaults to "GENERIC".

The incremented counter is guaranteed unique, guaranteed by Intersystems. Once you call it, there is no way to decrement it to its previous value no matter you use it or not. Also this increment is out of transaction control. So you can always remain assured that the counter you have obtained is unique in context to <cKeyword> throughout the system ( Database Server ).

This is pretty useful in having a unique field in your table which cannot be duplicated by any means.

<cKeyword> is case sensitive so that "Keyword" is not equal to "KeyWord". Take care.

CacheCreateDatabase ( cDatabase, cDirectory, nSize, nGrowthBlockSize, hConnection ) -> cResult

The function attempts to create Database on the Server and returns its status as a sting. "OK" if the database is created successfully or any other message what the server returns.

CacheCreateNamespace ( cNamespace, cDatabase, hConnection ) -> cResult

The function attempts to create <cNamespace> and maps <cDatabase> as its default database and returns "OK" if successful otherwise a string returned by the Server.

CacheSetDefinition ( cTable, aTableDef, cSchema, hConnection ) -> cResult

The function is an extension of RDD concept and controls the various behavior of a table. The function is likely to grow with time, so, please keep an eye over it.

Right now it is not activated.

 

Page url: http://www.vouch.info/cacherdd/index.html?cache_library_functions.htm