MAKE-SPECIAL

Creates a special Reality file interface to non-Reality objects.

Syntax

MAKE-SPECIAL filename{,data-section} keyword {parameters}

Syntax elements

The format of valid file and data section names is described in Rules for file and data section names.

Additional parameters

CSV keyword

hostfile {NOHEADING} {SEP=separator}

hostfileThe absolute path on the host file system (UNIX or Windows) of the CSV file for which you wish to create the special view.

NOHEADINGSpecifies 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}

hostfileThe full path-name of the file in the host environment (UNIX or Windows) for which you wish to create the special view.

delimiterSpecifies 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-sectionSpecifies data sectionreferenced by index.

indexSpecifies the index for which the special index view is to be created.

Restrictions

Normally SYSMAN account only, but can be used in another account if copied into its MD Master Dictionary - the dictionary file that defines an account. It contains items that point to the code executed by all the TCL commands, to SYSTEM accounts, and to other accounts by means of Q-pointers. The MD also includes all File Definition Items for the account and other items. . To have the command added automatically to new accounts, add it to the USER data section of the NEWAC file.

General comments

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 DELETE-FILE. Where this provides access to a host file (CSV or FILE), the associated host file is not deleted.

CSV view

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 item-ids, starting at one and increasing by one for each subsequent item. Any quotation marks enclosing data fields are removed.

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 item-id 0 and a data definition item is created in the dictionary for each field. The item-ids for these data definition items are created as follows:

• Each item-id is created from the field name by removing apostrophes and leading and trailing spaces. All other spaces are converted to periods.
• The resulting text is truncated to a maximum length of 30 characters.
• If there is an existing data definition item with this item-id, a unique numeric suffix is added.

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 CSV-COPY command. Any changes will be reflected in the associated host file.

CSV example

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

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

ENV view

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.

Environment example

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

FILE view

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 item-ids, starting at one and increasing by one for each subsequent item. If a delimiter is specified, each field in a line, separated by a delimiter character, appears as an attribute within the corresponding Reality item. If a delimiter is not specified, each field appears as an item with a single attribute.

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.

FILE example

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

GFB and LFB views

From the SYSMAN account, to count the number of GFBs currently allocated:

MAKE-SPECIAL GFBS GFB
COUNT GFBS

The maximum avaiable number of GFBs is related to the NumDataSects database configuration parameter.

Again in SYSMAN use:

MAKE-SPECIAL LFBS LFB

And then a given account can use:

COUNT /SYSMAN/LFBS

to count the number of unique files their port has open. (There is currently no way of counting items in another port's LFB table.)

ILOCKS view

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.

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.

Listing locks

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.

Listing locks held by a specific port

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.

Listing specific locks

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.

Item lock example

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.

INDEX views

Two keywords are provided with the MAKE-SPECIAL command which enable the system administrator to create read-only special views of thecontents of an index. They are INDEX-ITEM and INDEX-KEY. Refer to the description of the keyword syntax element.

INDEX example

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:

INDEX-ITEM View

: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

INDEX-KEY View

: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

LICENCE view

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.

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 less than 60 days away, the number of days until expiry is shown; if expiry is less than a year away, the month of expiry is shown; if expiry is more than a year away, the year of expiry is shown. If a negative number is shown, this is the number of days in the grace period.

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

LICENCE example

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.