Web Toolkit

Domain Free Remote Files Guide

Version 4.3
© Information | Capital
December 7, 2010
 Web Toolkit Developer Guide

Definitions

Remote File
A remote file is a Q-pointer to a file physically located on another
system that is accessible by the local account. Unlike standard Q-pointer
VOC definitions, the first line in a definition for a remote file definition is RQ.

Node
A node is the term for a remote system. A node is based on entries
located in the OS host’s table. Each node defined represents another system
to which an account can access remote files from a remote account.

Remote File Permissions

Each remote account, and in turn each remote file, must be set with
access permissions. These permissions control access and I/O operations
from remote systems.

TKT.COMMS
TKT.COMMS account must be installed on any system serving up, or
using remote files.

Version 4.3
 Web Toolkit Developer Guide

1 – Install of TKT.COMMS Account

1. Goto the TKT release account, and enter the database environment
at TCL.
2. At the command prompt, type:
TKT.INSTALL.COMMS
The following will occur:

Version 4.3
 Web Toolkit Developer Guide

1.1 – Post Install of TKT.COMMS Account

After the TKT.COMMS account is newly installed, the following

accounts must be setup for access by remote systems.

TKT.ADMIN
TKT.COMMS
UV

Please refer to section 5, Account and File Management, for details on how
to set up the accounts needed.

Version 4.3
 Web Toolkit Developer Guide

1.2 – TCP/IP Port Access Setup – Linux

1. Log into the system as root.

2. At the command prompt, type:
system-config-securitylevel

1. Using the TAB key, navigate to the CUSTOMIZE button, and hit enter.

Version 4.3
 Web Toolkit Developer Guide

1.2 – TCP/IP Port Access Setup - Linux

1. Using TAB, insure that the Ethernet cards are considered both as
Trusted Devices and as Masquerade Devices, by moving to each
entry and pressing the spacebar. When activated, an asterisk, “*”, will
be displayed.

2. Using TAB, navigate to the Other Ports field. If there is already any
entries, simply press the spacebar to add another entry.

3. Add 11001 to the Other Ports field, then TAB to the OK button and
press enter.

4. Back on the primary screen, TAB to the OK button, and press enter to
save the changes.

Version 4.3
 Web Toolkit Developer Guide

1.2 – TCP/IP Port Access Setup - Linux

1. Refresh the network settings so that the new changes will take effect,
by typing the following at the command prompt:

service network restart

Version 4.3
 Web Toolkit Developer Guide

1.3 – Starting the TKT.COMMS Socket Listener

1. After install, the following command needs to be issued to start the

Socket Listener:
/GSASYS/TKT/TKT.COMMS/bin/StartCommServer

Version 4.3
 Web Toolkit Developer Guide

2 – DMF Menu

1. Choose the ADMIN link from the main TKT development menu.

1. Choose the DomainFree Administration menu option. NOTE: The menu can
also be linked to the menu structure of an application. This prevents the
necessity for the TKT development to be authorized on a production server.

Version 4.3
 Web Toolkit Developer Guide

2 – DMF Menu

1. The following options are present on the DMF Administration menu:

Acct & File Management

This option is the process for defining accounts and files to be shared
in a remote setup.

AppID Management
This allows for defining of applications on the local system. It also
allows for defining applications on remote systems, based on nodename.
NOTE: This replaces the need to manually setup the WEB_DEVAPPS file.

Server Node Management

This allows for definitions of remote systems, as well as the local system.
NOTE: All nodenames MUST be present in the system’s host table.

Reference Objects Menu

This is a link to the menu that controls the definitions of Reference
Objects for the account being maintained.

Version 4.3
 Web Toolkit Developer Guide

3 – Server Node Management

1. Choose defined nodes by clicking the spyglass to generate a list.

Version 4.3
 Web Toolkit Developer Guide

3.1 - Server Node Entry

1. Enter the Server Node Name. This name MUST exists in the system’s host
table for access. In both AIX and Linux systems, the host table is
located at /etc/hosts. Once defined, the system should get a
response from the Server Node Name, when a PING command is
issued.
Example of node name:
The Prosecution Attorney server is located at 192.168.2.20. The Node
name will be prosatty. When entered into the hosts table, the PING
command will show:
# ping prosatty
PING prosatty: (192.168.2.20): 56 data bytes
64 bytes from 192.168.2.20: icmp_seq=0 ttl=255 time=0 ms
64 bytes from 192.168.2.20: icmp_seq=1 ttl=255 time=0 ms
64 bytes from 192.168.2.20: icmp_seq=2 ttl=255 time=0 ms

2. If the Server Node Name being defined is the local server, check the
box for Local Host Server.

3. If the Server Node Name is defined as the Master server holding the
data for the CIDX, aka Master Index, system; then check the box for
DMF Server.

Version 4.3
 Web Toolkit Developer Guide

3.1- Server Node Entry

4. If the Server Node Name being defined needs special network routing
rules to access, then enter the routes needed in the grid.

5. Enter the IP address for the Server Node Name in the field IP address
for remote file interface.

6. Enter the port number that the system will use for remote files in the
field Port Number. Usually the port number should be 11001.

7. If the Server Node Name being defined is the Local Host Server, and
the server should not allow incoming connections, then check the box
for Disable Inbound Connections to this Node. Remember, This is ONLY
valid for the Local Host Server node entry.

8. If the Server Node Name being defined should not allow for outbound
connections, then check the box for Disable Outbound Connections
to the Node.

Version 4.3
 Web Toolkit Developer Guide

3.1- Server Node Entry

9. Choose from the drop down in the field Node Database Type, the
database that the Server Node Name is running.

Version 4.3
 Web Toolkit Developer Guide

4 – Application ID Management

This process allows for the definition of all applications on a system,

whether it is a local or a remote system.
This process replaces the need to manually maintain the
WEB_DEVAPPS file on any system.

Enter the following into the grid provided for any application:

1. APPID is the real application id. NOTE: For applications which run from
multiple data accounts, each separate from each other, the APPID is
the common application id that all accounts share.

Version 4.3
 Web Toolkit Developer Guide

4 – Application ID Management

2. Called By is the application id that can call the defined APPID. This
allows for multiple entries of synonym application ids to be defined for
a single APPID.

Example of Usage:

For the application tkt, there are three separate data accounts.
Each account will be called by a unique name.

3. In the Domain Free Server Node field, enter the previously defined
node name that the application is located. NOTE: This should ONLY be
entered when the application is on a remote system.

4. In the Data Account Name field, enter the account name that the
application is running from. The account MUST BE defined in the
UV.ACCOUNT file.

Example:
For the tkt application, there are three accounts, as pictured
above, TKT.RELEASE.4.3, TKT.RELEASE.4.2a, and TKT.RELEASE.4.1bb

5. The field Data Path is entered once the Data Account Name is entered
based on the information found in the UV.ACCOUNT file.

Version 4.3
 Web Toolkit Developer Guide

5 – Account and File Management

The process for Account and File Management is where all permissions
are set for remote systems to access files and accounts.

After defining nodes and applications, the Account and File

Management process allows for the set up all the accounts and files that
are allowed to be accessed by the defined nodes.

Version 4.3
 Web Toolkit Developer Guide

5.1 – Account Setup

1. The process for Account and File Management, starts with a grid listing
of accounts on the system that are defined to be accessed by remote
systems.
2. Choose from the drop down, the Account Name to be allowed for
remote access.
3. When chosen, the field Default Access Permissions, will fill in with a
system default value of RWXSCDA. The permissions allowed are:
Permission Definition
R READ access is allowed.
W WRITE access is allowed.
X Execute of TCL verbs is allowed.
S SELECT and SSELECT access is allowed.
C CLEARFILE access is allowed.
D DELETE access is allowed.
A ADD access is allowed.

Multiple permissions are entered within the field.

EXAMPLES:
To give an account read and write permissions only, enter RW
To give an account read , write, add and delete permissions, enter
RWAD

Version 4.3
 Web Toolkit Developer Guide

5.1 – Account Setup

4. The field Owner’s Account defines the owner of the entered remote
access allowed Account Name. This field is mandatory. In most
circumstances, the Owner’s Account will be the same as the Account
Name.

5. The field Owner’s AppID defines the TKT application ID associated to

the Owner’s Account field.

6. Replicate Files Default is a drop down defining if the account entered

will have its files replicated to another system. Replication is another
part of Domain Free, and is discussed in another document.
For the initial entry, leave the system entered value of Default.

7. The action button Set Default File Properties allows for individual files
within the account, to be set up unique with separate and different
permissions from other files in the account.

Version 4.3
 Web Toolkit Developer Guide

5.2 – File Management Access Control

Once the action button Set Default File Properties is clicked for an
account in the Account Setup process, the File Management Access Control
process is launched.

This process allows for the setting of unique permissions on a per file
basis.

The process also allows for the definition of Reference Objects as well
as Programs that a remote system will be allowed to execute.

NOTE: The action button Remote Triggers is a feature to be introduced

in a future release.

To access detail permissions for a file in an account, do the following:

1. Locate the file to access in the provided grid.

2. Click the action button Detail Permissions.

Version 4.3
 Web Toolkit Developer Guide

5.2.1 – Detail Permissions for a File

1. For each remote system that will access the file, enter the defined
system in the Node Name field. Also, there is a spy glass which will
return a list of all defined nodes on the system.
2. If the permissions to the file are to be limited to a single remote
application, enter the application ID in the field Calling Application ID.
3. If the permissions to the file are to be limited to a single user, enter the
user name in the User Name field.
4. Enter the permissions for the file in the Permissions field.
5. When done, click the SAVE compute button, at the bottom of the
page. The global buttons, at the top of the screen, are NOT allowed.

Each file can contain multiple permissions settings based on the entries in the
grid. The access can be set by node, or by node and calling application, or
by node, by calling application, and by a specified user.

Each set permissions defined for a file must have an associated node.

NOTE: By entering permissions here, the system will REJECT access to the file, if
the access is being request by a node not defined in the grid.

Version 4.3
 Web Toolkit Developer Guide

5.2.2 – Reference Objects Tab

The second tab in the File Management Access Control allows for the
publishing of previously defined Reference Objects.

The check box labeled Publish allows for remote systems to be able to
access the Reference Object.

The action button Detail Permissions allows for the setup of unique
permissions to the Reference Object, just like with normal files in the account.

Reference Objects are discussed in its own document, and for now
should be left alone.

Version 4.3
 Web Toolkit Developer Guide

6 – Runtime Account Setup

Once all definitions have been entered, to enable the runtime account for
remote file operations, do the following:

1. At TCL, make a new VOC item called *BASIC.DIRECTIVE.

2. Enter the following on Line 1:
*$R
3. Save the new item.
4. Select the contents of the application’s source file.
5. R.BASIC the contents of the application’s source file.

With the new VOC item, and the re-compile of the source programs using
R.BASIC, the application is now ready for remote files.

NOTE: If a program is never to be remote file aware, then enter the following
comment line in the heading of the source:
*$NOR
Also, if the program calls other subroutines, each one of those subroutines
must have the *$NOR line.

Mixing programs containing *$NOR with other programs that do not have the
directive will cause unpredictable results. Do Not do this.

Version 4.3
 Web Toolkit Developer Guide

6.1 – Setup a Remote Q-Pointer

To create a remote Q-pointer in an account that will access a file on a

remote system, do the following at TCL.

1. Edit a new VOC item, that is the name of the new remote Q-pointer.
2. Enter the following on each line:
<1> = RQ
<2> = remote account name
<3> = remote file name
<4> = node name of remote system

NOTE: The literal letters RQ are required on line 1.

After saving the new VOC item, test the connection to the file by using the
R.LIST verb. Details on this verb can be found in section 8.

Version 4.3
 Web Toolkit Developer Guide

6.2 – Allow Remote Systems to Access a Process in the Runtime Account

As with all users on the local system, a WEB_USER entry must be created for a
remote system, so that the remote system can run processes in the local
runtime application account.

The User Id for a remote system will be:

nodename:calling_applicationID

Where:

Nodename is the defined node name of the remote system

Calling_applicationID is the application on the remote system that will

be running processes in the local runtime application.

No password is needed for the user.

Like with other WEB_USERS, the access permissions of this user must be setup
like any other local server.

Version 4.3
 Web Toolkit Developer Guide

7 – R.BASIC rules with Accounts that Are Remote Aware

Rule 1 Each program written outside of the normal FIND/LIST/PROCESS

screens, must have the top 8 lines set to specific contents. Line 1 will either
have the keyword PROGRAM or the keyword SUBROUTINE, at the beginning
of the line. The next 7 lines will contain an asterisk “*” as the first character.

Example Program:
001:PROGRAM HELLO.WORLD
002:*
003:*
004:*
005:*
006:*
007:*
008:*
009:PRINT ‘HELLO WORLD’
010:STOP
011:END

Example Subroutine:
001:SUBROUTINE HELLO.WORLD(ERR.MSG)
002:*
003:*
004:*
005:*
006:*
007:*
008:*
009:CALL WTK.OPEN.FILE(‘WEB_TEMP’,FILE.TEMP,ERR.MSG)
010:IF ERR.MSG # ‘’ THEN RETURN
011:PRINT ‘HELLO WORLD’
012:RETURN
013:END

This style of coding is required for use with remote aware accounts, and the
R.BASIC compiler.

This style of coding allows for use of the SOURCE CONTROL screen, and the
capturing of comments of changes to code.

Version 4.3
 Web Toolkit Developer Guide

7- R.BASIC Rules

Rule 2 How to write IF/THEN/ELSE statements

The following IF/THEN/ELSE is NOT allowed.

IF X=1 THEN
Y=1
ELSE
Y=10
END

The proper format a IF/THEN/ELSE statement is:

IF X=1 THEN
Y=1
END ELSE
Y=10
END

Or:
IF X=1 THEN Y=1 ELSE Y=10

Rule 3 I/O operations syntax

For each READ/WRITE/DELETE operation, the statement should be on its own

line.

Example:
The following is NOT allowed:
IF X=1 THEN READ MYDATA FROM MYFILE,MYID ELSE MYDATA=””

The statement should be:

IF X=1 THEN
READ MYDATA FROM MYFILE,MYID ELSE MYDATA=””
END

Version 4.3
 Web Toolkit Developer Guide

7- R.BASIC Rules

Rule 4 I/O operations and complex variables

For an I/O operation that uses a complex variable, no spaces are allowed. A
complex variable is usually a variable concatenated to another variable or
literal string.

Incorrect syntax:
READ MYDATA FROM MYFILE,MYID : “*” : MYCOMPANY ELSE MYDATA=””

Correct syntax:
READ MYDATA FROM MYFILE,MYID:“*”:MYCOMPANY ELSE MYDATA=””

Rule 5 I/O operations with the following keywords: ON ERROR, LOCKED,

THEN and ELSE

The standard syntax has documented in DataBasic must be followed for all
I/O operations and statements

Incorrect syntax:
READ MYDATA FROM MYFILE,MYID LOCKED
Y=1
THEN
X=1
ELSE
Z=1

Correct syntax:
READ MYDATA FROM MYFILE,MYID LOCKED
Y=1
END THEN
X=1
END ELSE
Z=1
END

Version 4.3
 Web Toolkit Developer Guide

7- R.BASIC Rules

Rule 6 I/O statements must have space separators for keywords

Each I/O statement, like READ and EXECUTE, must contain spaces as
separators between the keywords for the statement.

Incorrect WRITE syntax:

WRITE “ABC”ON MYFILE,MYID

Correct WRITE syntax:

WRITE “ABC” ON MYFILE,MYID

Incorrect EXECUTE syntax:

EXECUTE “LIST MY.FILE NAME DOB”CAPTURING MYRPT

Correct EXECUTE syntax:

EXECUTE “LIST MY.FILE NAME DOB” CAPTURING MYRPT

Rule 7 No Default File Variable Operations are allowed

Example:
OPEN ‘MYFILE’ ELSE PRINT ‘NO MYFILE’
R.BASIC does NOT support this.

The statement should be:

OPEN ‘MYFILE’ TO MYFILE ELSE PRINT ‘NO MYFILE’

Rule 8 For any program that calls subroutines, those subroutines must
be in the same remote aware state that the parent program is in.

As discussed in section 1, each remote aware account will have a VOC

entry for *BASIC.DIRECTIVE. However, if a program will never be remote
aware, then the programmer can enter *$NOR, to turn off remote aware for
that one program.

BUT, if the parent program is not remote aware, and the subroutines are
remote aware, this can cause unpredictable behavior.

Version 4.3
 Web Toolkit Developer Guide

7- R.BASIC Rules

Rule 9 DataBasic Functions

The following two functions are NOT supported with R.BASIC.

SSELECT This is akin to the SELECT function, and should not be used.
Instead, use EXECUTE and SSELECT the file.
FORMLIST This function will be supported in a future release.

The INDICIES function is supported, but only with the following syntax:
INDICIES(filevariable,indexname)
Or with:
INDICIES(filevariable,’’)

Version 4.3
 Web Toolkit Developer Guide

8 – Verbs for use with Remote Files

For each system that will access a remote system, a set of TCL verbs
are available for use. These verbs are ONLY valid for files defined as remote
Q-pointers.

R.LIST and R.SORT

These verbs allow for a LIST and SORT operation of a remote file.

R.SELECT
This verb will select item id’s from the remote file.

R.ED
This verb will allow for editing of an item in a remote file.

R.EXC
This verb allows for execution of a TCL verb in the remote system
account.

Version 4.3