jRCS Classes

This section defines the set of interfaces (C++ classes) exposed by the jBASE Remote Connectivity Client.

C++ Client Layer

The C++ client layer defines a set of classes, closely following the structure of the objects on remote server. The C++ library uses the built-in exception handling features of C++ to report errors to the application program using the library. It also hides the specifics of how I/O requests or replies are handled, so the only function that the user may need to supply is the optional terminal I/O handler.

The classes, defined in the client layer are listed below. As it is more common to use VB.NET or C# rather than C++, the .NET properties and methods are presented (Type P = Property, M = Method).

 

Class JException

This class is the most basic class of the client library. Its intended use is for error reporting as an argument to try-catch-throw constructs in C++. This class can be thrown by methods of various classes in the client library. The methods of class JException follow.

Name Type Description
Code M Retrieves the error code which caused this exception to be thrown

 

Class JIOHandler

Class JIOHandler is a callback interface used by the jBASE session object to handle terminal I/O, generated by the remote jBASE session. As opposed to other environments, terminal I/O for the session will be delivered directly to the client computer. The session object will then call accessor methods in JIOHandler to handle terminal input or output. The default implementation of this interface will simply print the generated output to the standard output, or wait for input on the standard input. The callbacks are invoked on the thread currently requesting service from the jBASE session. The methods and properties of the class are listed below:

Name Type Description
Input M Called by the session object whenever it detects that terminal input is requested by the remote server. The method should return a line of input, which will be provided to the jBASE session.
Output M Called by the session object whenever it detects that terminal output is pending. Returns a String parameter representing the characters being output.
TermType P Returns a curses-compatible terminal type string with the value of the TERM environment variable in jBASE.

 

Class JConnection

Class JConnection represents the connection or session object and is the fundamental object of the entire client library. Most functionality in the library builds around the JConnection object, and all other client-side objects are created by the connection class. JConnection methods and properties are listed below:

Name Type Description
Abort Transaction M Aborts the transaction on the current connection.
Attach Common M  
Call M Calls a cataloged subroutine specified by a supplied string on the jBASE host, passing it a jDynArray. Upon a successful call, the results are returned in the same jDynArray. The number of parameters is not changed by the method.
Close M Closes an already active connection. This method is implicitly called by the destructor.
CodePage P Returns a string indicating the CodePage for the current connection.
Date P Returns the date currently set on the server, in standard jBASE internal format.
DeleteList M Deletes a previously saved select list.
Dispose M  
EndTransaction M Ends the transaction on the current connection.
Execute M Executes a jShell command returning results. A PassList parameter will be a pointer to the select list passed to the command being executed. If a PassList parameter is omitted or specified as NULL, no PassList is assumed. See the JExecuteResults class for information on the properties which are available to determine the output of the Execute.
ExecuteAndStore M Executes a jShell command and allows the capture string to be stored on the host and fetched incrementally in chunks. See the Remote Execution with Incremental Fetch section below.
Finalize M  
GetList M Retrieves a previously stored select list.
Iconv M Performs input conversion on specified code using the conversion code supplied.
Oconv M Performs output conversion on specified source using conversion code supplied.
Open M Opens a new connection to the jRCS Remote Server. A constant JRCS_PORT is provided and can be substituted for the Port parameter if it is known that the jRCS Remote Server is listening on the default port.
OpenFile M Opens a jBASE file (jEDI) and returns a pointer to the file object.
StartTransaction M Starts a new transaction on the given connection.
HostCharacterEncoding P Returns the host character encoding for the current connection.
jBaseVersion P Returns the jBASE version currently running on the server.
Locale P Returns the locale name for the current connection.
Port P Returns the jBASE port number on which the current connection is active.
TermIOHandler P  
Time P Returns the time currently set on the server, in standard jBASE internal format.
TimeOut P The period of inactivity, in seconds, after which a connection will be closed. Timeout is only applicable when the jRCS client is waiting for a host call to complete. Default is -1

 

Remote Execution with Incremental Fetch

The remote command execution under jRCS has been enhanced to allow the capture string to be stored on the host and fetched incrementally in chunks. To accommodate this requirement, a new method was added to the JConnection class, called ExecuteAndStore. The method takes the following parameters:

  • A jSH statement to execute

  • A list object to be passed to the execute

  • An optional chunk size for data fetch (default is 2048 characters)

  • An optional String for the RETURNING clause

  • An optional variable to accept the return list

Class JCapture

The ExecuteAndStore method returns an object of class JCapture with the following properties and methods:

Name Type Description
AtEnd P This read-only property indicates whether the saved capture string has been exhausted. If this property returns True, a subsequent call to NextBlock() will return an empty string.
BlockSize P Gets/sets the current block size for subsequent calls to NextBlock(). This property is initialized to the block size specified in the call to ExecuteAndStore, or to the default of 2048. This property must be greater than zero.
NextBlock M Fetches the next block of data and returns it as a string. The block is at least the size specified in the ExecuteAndStore call or determined by the BlockSize property, up to the closest attribute mark. If the captured outputis exhausted, the function returns an empty string.
Rewind M Rewinds the current position in the captured output to the beginning.

It is understood that EXECUTE/PERFORM is an atomic operation under most multi-value databases and will have to run to completion before the JCapture object is made available. It is furthermore recognized that execution with capture can be a lengthy and memory-intensive process and no guarantees are made as to the speed of ExecuteAndStore().

 

Class JExecuteResults

The Execute and ExecuteAndStore methods return an object of class JExecuteResults with the following properties:

Name Type Description
Capture P Returns a JCapture object
CaptureString P Returns the CAPTURING variable as a string.
ReturnList P Returns the RTNLIST variable as a JSelectList.
ReturnString P Returns the RETURNING/SETTING variable as a string.

 

Class JFile

Class JFile encapsulates an open jBASE file object (jEDI). JFile provides access to common file operations, including reading and writing of records. JFile data access methods normally manipulate the objects of class JDynArray (dynamic arrays). Dynamic arrays are discussed in greater detail later in this document. The methods and properties of the JFile object are listed below:

Name Type Description
Close M Closes an open JFile object. This method is called implicitly by the destructor.
ClearFile M Deletes all records in the file.
Delete M Deletes a record with a specified key.
Dispose M Calls the destructor for the current JFile object.
GetIndices M Retrieves a dynamic array of file indices.
GetIndex M Retrieves a dynamic array containing index information for a specified index name.
OpenIndex M Opens a specified index name and returns a JIndex item.
Path P Gets a full path of the file represented by this object.
Read M Reads a record from the current file object via the provided key parameter and returns a JDynArray. If a "locked" parameter is passed as "true", the read also places a lock on the record (ReadU). If the read is locked and "wait" is passed as "true", the connection waits for the record to be unlocked. Otherwise an exception is thrown.
ReadNamedField M Reads a field from the current file object via the provided key parameter. The field name is specified by a string parameter. If a "locked" parameter is passed as "true", the read also places a lock on the record (ReadVU). If the read is locked and a "wait" parameter is passed as "true", the connection waits for the record to be unlocked. Otherwise an exception is thrown.
ReadV M Reads a field from the current file object via the provided key parameter. The field number is specified by a numeric attribute parameter. If a "locked" parameter is passed as "true", the read also places a lock on the record (ReadVU). If the read is locked and a "wait" parameter is passed as "true", the connection waits for the record to be unlocked. Otherwise, an exception is thrown.
Release M Releases a lock on the record in the current file using the specified key parameter.
ReleaseAll M Releases all locks held by the current file object.
Select M Generates a JSelectList from the keys in the current file. The list is created in the same order as keys are ordered in the file.
SSelect M Generates a JSelectList from the keys in the current file.
Write M Writes a record to the current file object using the supplied key parameter. The record data is passed in a JDynArray. If "unlock" is passed as "true" - the default behaviour - the record is unlocked after completion of the write operation. Otherwise, the lcok is kept (WriteU).
WriteNamedField M Writes a field to the current file object using the supplied key parameter. The field name within the record is also passed as a parameter. If "unlock" is passed as "true" - the default behaviour - the record is unlocked after write operation completed. Otherwise the lock is kept (WriteVU).
WriteV M Writes a field to the current file object using the supplied key parameter. The field number within the record is also passed as a parameter. If "unlock" is passed as "true" - the default behaviour - the record is unlocked after write operation completed. Otherwise the lock is kept (WriteVU).

 

Class JDynArray

Class JDynArray encapsulates the functionality of a jBASE dynamic array. This class is different from other classes in the hierarchy in the sense that the dynamic array is fully handled locally on the client system and generates no calls to the jBASE host. This considerably speeds up dynamic array operations and incurs no penalty of remote calls. The methods of JDynArray are shown below:

Name Type Description
Count M Counts the number of times a specific character occurs within a dynamic array.
DCount M Counts the number of fields separated by the specified delimiter.
Delete M Deletes the attribute, value or sub-value specified. If the value-mark count is 0, the whole attribute is deleted. If the value-mark count is not 0, but the sub-value mark count is 0, the value specified by the attribute-mark count and value-mark count is deleted. Otherwise, a sub-value defined by attribute-mark count, value-mark count and sub-value mark count is deleted.
Extract M Extracts a string from an attribute, value or sub-value of the dynamic array. The same rules apply as shown in the description of the Delete method.
ExtractDA M Same as Extract but stores the results in a dynamic array.
Field M Returns nth field separated by specified delimiter.
Insert M Inserts a string into the position designated by attribute value and sub-value mark count specified. The same rules apply as for Delete and Extract functions, with one exception. A value of -1 is permitted for attribute, value or sub-value mark count. If this negative value is detected, then data is inserted at the end of the selected list of attributes, values or sub-values.
InsertDA M Same as Insert, but inserts a JDynArray.
Length P Returns the length, in characters of a dynamic array.
Locate M Finds the position of a string within the specified locations of a dynamic array.
LocateIgnoreCase M Finds the position of a string within the specified locations of a dynamic array, ignoring case when matching strings.
Replace M Replaces the data addressed by the attribute, value and sub-value mark count specified with a string or JDynArray. The same rules apply as for Delete and Extract.

 

Class JSelectList

Class JSelectList wraps around a jBASE select list. It can be created either by the connection or the file object, and supports all the basic select list functions. The methods of class JSelectList are listed below:

Name Type Description
IndexKey P Retrieves the index key for the current record.
IsIndex P Indicates whether the select key was generated from the index or from a Select operation.
ReadNext M Reads the next key - index or record key - from the select list.
RecordKey P Retrieves the record key corresponding to the current index key.
SaveList M Saves the select list under the specified list name.

 

Class JIndex

Class JIndex enables the functionality of jBASE indexes. This class allows generation of select lists from jBASE indexes. Methods of class JIndex are shown below:

Name Type Description
Select M Generates a select list from the index and positions, and optionally the list pointer at the specified index key.

 

Class JCommon

Class JCommon encapsulates the functionality of jBASE common block (both named and unnamed). It provides basic operations to get data from and put it into the common block. The methods of class JCommon are listed below:

Name Type Description
GetDA M Retrieves a dynamic array from the designated position in the common block.
GetFile M Retrieves a file variable from the designated position.
SetDA M Stores a dynamic array at the designated position in the common block..
SetFile M Stores a file variable at the designated position in the common block.

jBASE Remote Connectivity Service