Library Functions

cServerIPorAddress

nPort

cUsername

cPassword

nTimeout

cNamespace

hConnection

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.

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.

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.

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.

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.

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:

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

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.

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.

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:

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

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.

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.

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.

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.

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.

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".

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".

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".

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".

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.

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.

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

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

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.

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.

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,;

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.

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.

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:

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.

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.

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

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>.

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

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.

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.

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.

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.

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.

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.

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.

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

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

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

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 :

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.

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.

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.

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.

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.

The function tries to upload a .DBF as raw bytes in 32 kb chunks. It is an extremely fast mechanism to upload data or transfer tables to Cache. It is a handy mechanism to put existing tables in Cache in a phased manner. Please note that no indexes are created under this protocol.

<cDbf> the fully qualified path of a valid .DBF ( DBFCDX or DBFNTX ). DBFCDX driver is used to open the table without any indexes.

<cTable> the name of the table in the database. The name must be a bare name, no path or extension included. It is normalized to upper case.

[<cSchema>] schema name where this table will be created. By default it is "SQLUSER".

[<lEraseIfExist>] flag to specify if the table on the server be dropped first. By default it is FLASE.

[<bExeBefore>] block to be executed prior to starting the upload process as : bExeBefore := {| cDbf, nTotalRecords | DispUploadStatus( cDbf, nTotalRecords ) }

[<bExeDuring>] block to be executed during upload process after every [<nEvery>] records as : bExeDuring := {| nRecsUploaded | DispUploadStatus( nRecsUploaded ) }

[<nEvery>] wait for number of records to upload for evaluating [<bExeDuring>] block.

[<bExeAfter>] block to be executed after all records have been uploaded as: bExeAfter := {| cDbf, cTable, nRecordsUploaded, nRecsInTable | DispUploadStatus( cDbf, cTable, nRecordsUploaded, nRecsInTable ) }

CacheMGR offers an option to upload .dbfs and displays the progress of such uploads on its interface. Once uploaded, you can take use of its other option <Create Index by Tag>

The function tries to download a .DBF as raw bytes in 32 kb chunks. It is an extremely fast mechanism to download tables to disk. Please note that no indexes are managed under this protocol.

<cTable> the name of the table in the database. The name must be a bare name, no path or extension included. It is normalized to upper case.

[<cSchema>] schema name where this table will be created. By default it is "SQLUSER".

<cDbf> the fully qualified path of a valid .DBF ( DBFCDX or DBFNTX ). DBFCDX driver is used to create the table without any indexes.

[<lEraseIfExist>] flag to specify if the table on the server be dropped first. By default it is FLASE.

[<bExeBefore>] block to be executed prior to starting the upload process as : bExeBefore := {| cDbf, nTotalRecords | DispUploadStatus( cDbf, nTotalRecords ) }

[<bExeDuring>] block to be executed during upload process after every [<nEvery>] records as : bExeDuring := {| nRecsUploaded | DispUploadStatus( nRecsUploaded ) }

[<nEvery>] wait for number of records to upload for evaluating [<bExeDuring>] block.

[<bExeAfter>] block to be executed after all records have been uploaded as: bExeAfter := {| cDbf, cTable, nRecordsUploaded, nRecsInTable | DispUploadStatus( cDbf, cTable, nRecordsUploaded, nRecsInTable ) }