Creates a special Reality file interface to non-Reality objects.
MAKE-SPECIAL filename{,data-section} keyword {parameters}
filename The name of the special view file to be created.
data-section The name of a data section within the specified Reality file. If omitted, the default data section is used.
The format of valid file and data section names is described in Rules for File and Data Section Names.
keyword specifies the type of special file to be created. The following keywords can be used:
CSV Specifies a special view of a text file in comma-separated value format on the host file system (UNIX or Windows). This keyword requires additional parameters.
ENV Specifies a special file interface to the host environment (UNIX or Windows). No additional parameters required.
FILE Specifies a special view of a text file on the host file system (UNIX or Windows). This keyword requires additional parameters.
ILOCKS Specifies a special view of the item lock table, showing locks that are in contention. No additional parameters required.
The next two index view keywords require additional parameters.
INDEX-ITEM Specifies a view of the index key values for the set of items in the data-section selected by the referenced index. Items in an INDEX-ITEM view file have the same item-ids as their associated data items, selected by the index, with associated key values in attribute one.
INDEX-KEY Specifies a view of the item-ids associated with each key value in a referenced index. Items in the INDEX-KEY view file have numeric item-ids that reference the 1st to the nth unique keys in the index.
Each item comprises two attributes. The first containing the key value for the associated unique key item id and the second containing a multi-valued list of the data item-ids associated with the key value in attribute one.
Note: A third index view, INDEX-RAW, is provided for use by Northgate Support personnel only.
LICENCE Specifies a view of the Reality licence and connection counts.
NULL Specifies a null device file. No additional parameters required.
parameters Some keywords require additional parameters. See Additional Parameters below.
CSV keyword
hostfile {NOHEADING} {SEP=separator}
hostfile The absolute path on the host file system (UNIX or Windows) of the CSV file for which you wish to create the special view.
NOHEADING Specifies that the CSV file has no initial heading line. If omitted, the first line of the file is assumed to contain the names of the data fields.
SEP=separator
Specifies that data fields in the CSV file are delimited by the single character
separator. If omitted, a comma is used.
FILE keyword
hostfile {delimiter}
hostfile The full path-name of the file in the host environment (UNIX or Windows) for which you wish to create the special view.
delimiter Specifies the character(s) to be converted to an attribute mark. If delimiter is not specified, no attribute marks are inserted in the file view item.
INDEX-ITEM and INDEX-KEY keywords
data-section index
data-section Specifies data section referenced by index.
index Specifies the index for which the special index view is to be created.
Normally SYSMAN account only, but can be used in another account if copied into its MD. To have the command added automatically to new accounts, add it to the USER data section of the NEWAC file.
A special file is virtually indistinguishable from an ordinary Reality file. This enables the referenced host environment to be accessed and manipulated using standard TCL commands, as well as other processors, such as English, DataBasic, Proc, etc.
More than one special file can be created and can co-exist for the same host file, each constituting a synonym file name for the same special file view.
A Reality special file can be deleted with
The CSV keyword specifies a special view of a text file in comma-separated value format on the host file system (UNIX or Windows).
If the specified host file exists, each line becomes an item in the special
Reality file. The data items are given numeric
Unless the NOHEADING keyword is included, the
first line of the host file is considered to be a heading line, containing the
names of the data fields. This heading line is given the
An English macro, 1, is created in the dictionary to list all the data fields from the CSV file.
Note that the English commands LIST, SORT, SELECT, etc. do not list the heading item.
If the NOHEADING keyword is included, no heading item or data definition items are created.
If the specified host file does not exist or is empty, and the dictionary of the specified Reality file already exists, a heading item is created from the existing data definition items, if any.
Once created, the special Reality file can be manipulated in the same way as
any other Reality file. The contents of another Reality file can be copied to a
CSV file with the
If the Windows file c:\temp\union.csv contains the following:
"Surname","City","Country" "Wilkinson","Newcastle","UK "O'Driscoll","Dublin","Eire" "Michalak","Paris","France"
the following command creates a Reality view of this file:
:MAKE-SPECIAL UNION CSV c:\temp\union.csvThis can then be viewed from Reality as follows:
:LIST UNION Page 1 13:43:58 06 Apr 2005 Surname... City...... Country... Wilkinson Newcastle UK O'Driscoll Dublin Eire Michalak Paris France 3 Items listed. :
The ENV keyword specifies a special file interface to the host environment (UNIX or Windows). The file created contains an item for each host environment variable – the item id is the variable name and the value of the variable is in attribute one. You can change your current host environment by updating items in this file.
Create a special file interface to your UNIX environment.
REALROOT=/realman/9.0 SHELL=/bin/ksh PWD=/user1/admin REALACC=SYSMAN etc.
Enter
MAKE-SPECIAL ENVFILE ENV
The following system message is returned:
[417] FILE 'ENVFILE' created. D code =D, modulo =1, separ = 1 [417] FILE 'ENVFILE' created. D code =DX, modulo =0, separ = 0
Now if you enter:
CT ENVFILE *
the following items will be displayed:
REALROOT 001 /realman/9.0
SHELL 001 /bin/ksh
PWD 001 /user1/admin
REALACC 001 SYSMAN
The FILE keyword specifies a special view of a text file on the host file system (UNIX or Windows).
Lines of text within the referenced host file appear as Reality items
in the special Reality file (see File Example). The
items are given numeric
Even if the specified host file does not exist, MAKE-SPECIAL will still create a D-pointer in the MD and a special file dictionary. However, any attempt to view such a file will return the error message:
[201] Unable to open file 'filename'.
Special file view is primarily for viewing text files. An attempt to create a special view on to a binary file and manipulate binary data will have an undefined effect. Also a special file view is a read only file. Any attempt to write to it will result in an error message.
Create a special view of the file /user1/admin/addresses which contains data in the format:
John Smith:24, Brandles Close:Letchworth:Herts:SG6 6QW Alan Brown: 67, South Avenue:Littleover:Derby:DE3 6GH Alison Macdonald:23 Castle Road:Southampton:Hants:SO2 5FE
Enter:
MAKE-SPECIAL ADDRESSES FILE /user1/admin/addresses :
The following system message is returned:
[417] FILE 'ADDRESSES' created. D code =D, modulo =1, separ = 1 [417] FILE 'ADDRESSES' created. D code =DX, modulo =0, separ = 0
Now if you enter:
CT ADDRESSES *
you will see the following items:
1 001 John Smith 002 24, Brandles Close 003 Letchworth 004 Herts 005 SG6 9QW 2 001 Alan Brown 002 67, South Avenue 003 Littleover 004 Derby 005 DE3 9GH 3 001 Alison Macdonald 002 23 Castle Road 003 Southampton 004 Hants 005 SO2 5FE
The ILOCKS keyword specifies a special view of the item lock table, showing locks that are in contention. Each item lock appears as an item in the special Reality file.
Note: Reality V11.0 introduced a number of enhancements to this feature. As a result, item locks files that were created on earlier version of Reality will not show the detailed item lock information described below. To view the lock details you will have to create new item locks files. For example, if your item lock file is called ILOCKTAB enter the following command:
:DELETE-FILE ILOCKTAB:MAKE-SPECIAL ILOCKTAB ILOCKS
An item lock view file is read only. Any attempt to write to it will result in an error message.
When you create the special view file, a set of attribute definition items are copied into the special file dictionary which are used by the English processor to display the item locks report.
The default macro (1) generates a report with the following headings:
| Heading | Meaning |
|---|---|
| Lock ID | Lock identifier. |
| Port | Number of port holding lock. |
| Wait | List of ports waiting for this lock. |
| File | The file and data section name. |
| Item | The ID of the locked item. |
The following dictionary items are provided, so that you can create your own reports:
| Name | Displays |
|---|---|
| 1 | Default macro. |
| COUNT | Number of locks held. |
| DETAILS | Macro that provides a listing with the following headings: Value, File Hash, Item Hash, Port, Lock Count, Level, Waiting, Waiting Level. |
| FILE-HASH | File hash part of item lock ID. |
| IACCOUNT | The name of the account containing the file. |
| IDATA | Name of file data section. |
| IDICT | Name of file dictionary. |
| IFILE | Combination of IDICT and IDATA. |
| ITEM | The ID of the locked item. |
| ITEM-HASH | Item hash part of item lock ID. |
| LEVEL | Level of lock. |
| LOCK-VALUE | The lock ID (combination of ITEM-HASH and FILE-HASH). |
| PORT | The number of the port holding the lock. |
| PORTS | Macro used when displaying locks on specific ports. |
| WAIT | Same as WAITING. |
| WAITING | A multivalued list of ports waiting on the item lock. |
| WAITING-LEVEL | The level that lock is being waited on. |
To list locks that are preventing access by other ports, simply use the LIST command to list the item locks file. For example, the following command creates an item locks file called ILOCKTAB:
MAKE-SPECIAL ILOCKTAB ILOCKS
The locks that are preventing access by other ports can then be listed with:
LIST ILOCKTAB
A report similar to the following is displayed:
Page 1 13:48:50 09 Mar 2004
Lock ID......... Port Wait File................ Item.....................
0081C0C100028E1B 401 402 TEST 000001
403
One item listed.
This shows that port 401 is holding a lock on item 000001 in the file TEST, and that ports 402 and 403 are waiting for this item.
See also ILOCKS Example.
To list the locks held by a specific port, use the PORTS macro and specify the required port numbers. For example, if you have called the item locks file ILOCKTAB, enter:
LIST ILOCKTAB PORTS '401' '402' '403'
You will see a report similar to the following:
Page 1 14:01:13 09 Mar 2004
Port Wait File................ Item..........................
401 402 TEST 000001
403
401 TEST 000002
401 TEST 000003
401 TEST 000004
401 TEST 000005
401 TEST 000006
401 TEST 000007
401 TEST 000008
401 TEST 000009
401 TEST 000010
402 WAIT TEST 000001
403 WAIT TEST 000001
3 Items listed.
This shows that port 401 is holding 10 locks and ports 402 and 403 are waiting for the lock on item 000001 in the file TEST.
Although listing the item lock view file shows only those locks that are in contention, if you know the lock ID, you can obtain details of a specific lock (you can use the LIST-ITEM-LOCKS and SHOW-ITEM-LOCKS commands to obtain the ID of a lock). For example:
LIST ILOCKTAB '0081C0C100028E1B'
A report similar to the following is displayed:
Page 1 13:48:50 09 Mar 2004
Lock ID......... Port Wait File................ Item.....................
0081C0C100028E1B 401 402 TEST 000001
403
One item listed.
This shows that lock 0081C0C100028E1B is being held by port 401 on item 000001 in the file TEST, and that ports 402 and 403 are waiting for this item.
Create a special view of the item lock table. For example, enter:
MAKE-SPECIAL ILOCKTAB ILOCKS
then, enter:
LIST ILOCKTAB
This will display a report similar to the following:
Page 1 13:48:50 09 Mar 2004
Lock ID......... Port Wait File................ Item.....................
0000031000000058 405 402 GUESTS 003752
404
403
One item listed.
This shows that port 405 is holding a lock on item 003752 in the file GUESTS, and that ports 402, 403 and 404 are waiting for this item.
Two keywords are provided with the MAKE-SPECIAL command which enable the system administrator to create read-only special views of the contents of an index. They are INDEX-ITEM and INDEX-KEY. Refer to the description of the keyword syntax element.
Create an index GUESTS-LAST-NAME for the GUESTS data section which has index entries ordered according to the key value LAST-NAME. For example:
:DEFINE-INDEX GUESTS BY LAST-NAME TO:GUESTS-LAST-NAME [1281] Index definition 'GUESTS-LAST-NAME' created.
:CREATE-INDEX GUESTS GUESTS-LAST-NAME [1280] Index 'GUESTS-LAST-NAME' created.
Then using the MAKE-SPECIAL command create two special views of the index GUESTS-LAST-NAME. For example, GSN-ITEM-VIEW and GSN-KEY-VIEW, as follows:
:MAKE-SPECIAL GSN-ITEM-VIEW INDEX-ITEM GUESTS GUESTS-LAST-NAME [417] File 'GSN-ITEM-VIEW' created. D code =D, modulo = 1, separ = 1 [417] File 'GSN-ITEM-VIEW' created. D code =DY, modulo = 0, separ = 0
:MAKE-SPECIAL GSN-KEY-VIEW INDEX-KEY GUESTS GUESTS-LAST-NAME [417] File 'GSN-KEY-VIEW' created. D code =D, modulo = 1, separ = 1 [417] File 'GSN-KEY-VIEW' created. D code =DY, modulo = 0, separ = 0
Now look at the items in the two special view files using the CT command. For example:
:CT GSN-ITEM-VIEW *
100 001 Anderson
122 001 Anderson
444 001 Curtis
535 001 Evans
289 001 Fennelly
365 001 Ferguson
411 001 Gallagher
143 001 Hennessey
194 001 Hynes
144 001 Irving
147 001 Janson
478 001 Kolman
211 001 Lewis
412 001 Lewis
140 001 Lynch
142 001 Madison
234 001 McSweeney
309 001 Mendell
222 001 O'Brien
401 001 Palmer
318 001 Petrillo
428 001 Postma
117 001 Rizzo
119 001 Scott
354 001 Taylor
355 001 Taylor
Note: For exploding indexes the item ID will have the multi-value and sub-value numbers appended. For example, an item ID of ‘355’ will look like ‘355 <1>’ if values are exploded, or ‘355 <1,1>’ if sub-values are exploded.
:CT GSN-KEY-VIEW *
1 001 Anderson 002 100]122
2 001 Curtis 002 444
3 001 Evans 002 535
4 001 Fennelly 002 289
5 001 Ferguson 002 365
6 001 Gallagher 002 411
7 001 Hennessey 002 143
8 001 Hynes 002 194
9 001 Irving 002 144
10 001 Janson 002 147
11 001 Kolman 002 478
12 001 Lewis 002 211]412
13 001 Lynch 002 140
14 001 Madison 002 142
15 001 McSweeney 002 234
16 001 Mendell 002 309
17 001 O'Brien 002 222
18 001 Palmer 002 401
19 001 Petrillo 002 318
20 001 Postma 002 428
21 001 Rizzo 002 117
22 001 Scott 002 119
23 001 Taylor 002 354]355
Note: For exploding indexes attribute 3 will contain the multi and sub-value numbers separated by a value mark.
The LICENCE keyword specifies a view of the Reality licence and connection counts. Each licence type appears as an item in the special Reality file.
Note: A licence view special file called REALITY-LICENCE is supplied in the SYSMAN account.
A licence view file is read only. Any attempt to write to it will result in an error message.
When you create the special view file, a set of attribute definition items are copied into the special file dictionary which are used by the English processor to display a report of Reality licences with the following headings:
Licence Type The type of connection.
Maximum Licence The number of available licences of this connection type. This
will normally only be non-zero for the Ordinary, Reserved and RLTYXDSP
connection types.
Used Licence The number of licences of this connection type that have been used.
Database Used Port
The number of connections of this type that are currently in use.
Reserved Ports The number of
licences successfully reserved for specific connection types.
Request Reserve The number of reserved licences requested. This should normally be the same as the number of Reserved Ports.
Spare Ports The number of free, unallocated
licences.
Expires The date on which the licences expire. If expiry is in less than 60 days, the number of days until expiry is shown.
Licensed Ports The total
number of all types of licence.
The report lists the following connection types:
Ordinary User licences. For normal user connections, one licence is required for each
connected user. User licences can also be used for other connection types if no
licences of the required type are available.
Reserved Licences reserved for use by specified PLIds.
TempUser Temporary user licences.
SQLSRVR Network connections to the SQL server. You can reserve
licences for this purpose by setting the REALRESERVESQLSRVR
environment variable
to the number of licences required.
RLTYXDSP Despooler connections.
You can reserve licences for this purpose by purchasing
despooler licences or setting the REALRESERVERLTYXDSP environment variable
to the number of licences required.
TIPH TIPH connections. You can reserve licences for this purpose by purchasing TIPH licences.
ROSFS Network connections to the remote file server.
You can reserve licences for this purpose by setting the REALRESERVEROSFS environment variable
to the number of licences required.
RSCSRVR Network connections to the remote subroutine server.
You can reserve licences for this purpose by setting the REALRESERVERSCSRVR environment variable
to the number of licences required.
RWSRVR Network connections to the RealWeb server.
You can reserve licences for this purpose by setting the REALRESERVERWSRVR environment variable
to the number of licences required.
GUISRVR Network connections to the GUI Admin server. Five ports are set aside
for these connections and can be used even if there are no user licences
available.
SYSTEM System utilities such as realresize,
pdump,
realmt,
realdump,
fsadm,
tlrestore and
realusers. Five ports are set aside for these utilities and can be used even
if there are no user licences available.
TLMENU Commands run by the
tlmenu host utility.
A single port is set aside for this; it can be used even if there are no
user licences available.
CRITICAL Other commands that must be able to run, even if there is no user licence
available. A single port is set aside for this.
Create a special view of the licence table. For example, enter:
MAKE-SPECIAL LICENCE LICENCE
then enter:
LIST LICENCE
This will display a report similar to the following:
Licence.. Maximum Used.... Database. Reserved Request Spare Expires Licensed Type Licence Licence Used Port Ports Reserve Ports (Days) Ports Ordinary 104 100 100 0 0 4 - 120 Reserved 2 1 1 2 0 1 - TempUser 0 0 0 0 0 0 - SQLSRVR 0 2 2 3 3 1 - RLTYXDSP 16 10 10 0 0 6 - ROSFS 0 0 0 0 0 0 - RSCSRVR 0 0 0 0 0 0 - RWSRVR 0 0 0 0 0 0 - GUISRVR - - 0 - - 5 - SYSTEM - - 1 - - 4 - TLMENU - - 1 - - 0 - CRITICAL - - 0 - - 1 - 12 Items listed.