jBASE Remote Connectivity Service jRCS

1
jBASE Remote Connectivity Service (jRCS)

• Technical Overview
• By Alex Lashchuk
• Sanderson CMI

2
Who We Are

• Sanderson CMI
• Provider of software for local governments
• Part of Sanderson Group
• Large multivalue user and jBASE VAR
• Alex Lashchuk
• Senior software engineer
• Designer and implementer of jRCS

3
Agenda

• Overview
• Architecture and Protocol
• Discussion of C and ActiveX jRCS APIs
• Conclusion
• Questions

4
Overview
5
What Is jRCS ?

• Client-server connectivity solution
• Handler for remote client requests
• File I/O
• Dynamic array manipulation
• Conversions
• Remote subroutine calls and program execution

6
Why jRCS ?

• Facilitates implementation of GUI products
• Enables multi-tier application architecture
• Based on open standards
• TCP/IP communication
• XML-based protocol
• Client APIs can be ported to most environments

7
jRCS vs. OBjEX

• Similarities
• Client/server connectivity products
• Similar client APIs
• Differences
• Remote vs. distributed model
• jRCS is more lightweight
• jRCS works across platform boundaries

8
Architecture and Protocol
9
jRCS Structure

• Server
• Daemon on Unix (jrcsd)
• Service on Windows (jrcs.exe)
• Client libraries
• Raw C layer
• jrcs.dll on Windows
• jrcs.so or jrcs.a on Unix
• ActiveX layer (Windows only)
• jrcax.dll

10
jBASE Connectivity Markup Language (JCML)

• Communication protocol for jRCS
• XML-based
• Transmitted over TCP/IP
• Efficient and easy-to-parse
• Supports escaped and base64 encoding of dynamic
  strings
• Portable
• Allows implementation of clients on many
  platforms and in many languages

11
Sample JCML Request

• Logon request
• Sent after TCP/IP connection is established

lt?xml version"1.0" encoding"UTF-8"?gt ltjcml
type"req" src"client"gt ltobjgt0lt/objgt ltcmdgtopenlt
/cmdgt ltdata enc"esc"gtMYUSERlt/datagt ltdata
enc"esc"gtMYPASSWORDlt/datagt ltdata
enc"esc"gtMYACCOUNTlt/datagt ltdata
enc"esc"gtlt/datagt ltdata enc"esc"gtvt100lt/datagt lt/
jcmlgt
12
Sample JCML Reply

• Successful logon reply
• Sent by the server after a logon request is
  successfully processed

lt?xml version"1.0" encoding"UTF-8"?gt ltjcml
type"reply" src"server"gt ltstat id"0"gtNo
errorlt/statgt ltdata enc"esc"gt15000lt/datagt lt/jcmlgt

13
jRCS Server Features

• Process isolation
• Each session starts its own server process
• Each connection gets a separate jBASE port
• Security
• Authentication performed through OS logon
  procedures
• Each server process runs with identity of the
  authenticated user

14
jRCS Environment Variables

• Startup variables
• JBCGLOBALDIR
• JBCRELEASEDIR
• PATH or LD_LIBRARY_PATH or LIBPATH
• Variables established at logon
• Any system variable can be set
• Configuration script
• .jrcsrc on Unix
• jrcsrc.cmd on Windows

15
jRCS API
16
Overview of Client API

• API isolates client process from JCML and TCP/IP
  layer
• Contains proxies for server objects
• Defines constants for error codes
• Implemented in C
• Contains an ActiveX layer on Windows
• Built on top of C API

17
Client API Classes
18
Connecting to Host the jConnection Object

• First object created by the client application
• Open method sends logon info to the server
• Host name and TCP port
• User name (must be a valid OS user on the host
  machine)
• Password
• Account name (optional, must be a valid OS user)

19
jConnection (Continued)

• Session-level operations
• Contains AM, VM, SVM constants
• Server date/time querying
• Conversions
• Function calls
• Command execution
• Opening files, select lists and indexes

20
Dynamic Arrays the jDynArray Object

• Manipulates a single dynamic array
• String assignment and retrieval
• Attribute extraction
• Attribute replacement
• Attribute insertion
• Attribute deletion
• Count/DCount
• FIELD() functionality

21
jDynArray Internals

• Internal operation
• Local implementation (no host requests are made)
• Indexed string representation
• Index generation and compaction
• Lazy cloning
• Best practices

22
File I/O the jFile Object

• Manipulates a single file open by jConnection
• Operations
• Read, ReadU, ReadV, ReadVU
• Write, WriteU, WriteV, WriteVU
• Select, SSelect
• Delete, Release
• Clearing files
• Opening Indexes

23
Select Lists the jSelectList Object

• Performs select list manipulation
• Operations
• ReadNext
• EOL, BOL indicators
• Current record and index key properties
• Saving of lists
• Example

24
Remote Command Execution

• Execute and ExecuteAndStore methods
• Storing results on the host and incremental fetch
• jCapture object
• NextBlock method
• Example

25
Remote Procedure Calls

• The Call method
• Remote vs. local execution
• Subroutines execute on the host, not client
• No jRFS or jBASE runtime necessary on the client
• Host subroutine requirements and parameter
  matching
• Example

26
Terminal I/O Handling and Host Debugging

• Terminal I/O data sent to the client via JCML
• jRCS client opens a console window with limited
  vt100 emulation for the output
• Client program can override default I/O handling
• The jIOHandler interface
• Use for debugging purposes only

27
Summary
28
Summary

• JRCS is a client/server connectivity solution for
  jBASE
• jRCS is based on an open, XML-based protocol
  (JCML)
• jRCS provides access to a broad number of
  features in jBASE
• Client API for jRCS isolates the programmer from
  parsing JCML directly

29
Questions