REGISTRYC(0;SPACEBANK,METER,SB ==> c;REGISTRY)

A registration facility is created.

The registry is self dissolving. When names are deleted from the registry some record collections behind the REGISTRY key become empty. The normal action is for these empty record collections to be deleted {and the name entry in the next higher record collection}. Note that the DIRECTORY key given to the REGISTRY key will never be destroyed by the registry facility.

Return codes - see (p3,fact-ret-codes).

Produce a registry that is not self dissolving. When names are deleted from the registry some record collections behind the REGISTRY key become empty. The normal action is for these empty record collections to be deleted {and the name entry in the next higher record collection}. With non-dissolving REGISTRY keys this does not happen. This is useful if sub directories are shared.

Return codes - see (p3,fact-ret-codes).

Registration key

A registry supports a convenient naming convention for accessing keys in a tree of record collections. This is the standard now used within the command system. The registry thus provides a common access method for a tree of record collections.

A registry has no state except whether it is self-dissolving.

By convention, names of record collections that are part of a directory tree end with a dot "." and represent levels of the tree. If the REGISTRY key finds any names in the directory structure that end with dots "." that are not name sequence record collections, it replaces the key with a name sequence record collection {when adding to the tree only}.

Names may contain any upper case EBCDIC letter, number and the special symbols "&!%#-|"+^/;()<>{}", not sign, and left and right square brackets. The character "*" designates a "wild card" and represents an arbitrary string of arbitrary length without "."s. The character "?" represents a single arbitrary character. There may be wild cards at each level but no more than one "*" at each level.

N.B. "*.*" includes the name "A.B" but not "A.B.C".

In CMS all names have three parts thus "* * *" specifies all of each part. In Gnosis the directory structure is not rigid. In fact there is no reason why the name "A" and "A.B" cannot coexist. This is not a traditional specification of a catalog tree structure. The presence of "A" would normally prohibit the presence of "A.". What this means is that "*.*" in Gnosis specifies all two level {"A.B." satisfies "*.*" !} names, but does not specify one level names.

The registry also supports a tree structure of names without dots. To specify names in this structure the character "~" {tilde} is used. In this context the "~" is NOT part of any name. "A~B" specifies a record collection "A" that has a record in it with the name "B". "A~*" specifies every record in the record collection "A" and acts like the TYPE command in CMS {provided that "A" is a named sequence record collection}. These two forms can be mixed. The significance of the "." or the "~" is only related to the syntax of the name specification and not the function of the registry.

REGISTRY(0,(key name,descriptive material);DIRECTORY,key ==> c) Add a name and key to the directory structure.

"key name" is a character string with embedded dots ".". The name must not contain any wild card designators.

"Descriptive material" is a string of bytes that begins with a ",".

The convention of separating the key name from the descriptive material with a "," is chosen because the vast majority of names will be recorded without descriptive material, and in such cases only the string that represents the key name need be present. The fact that this convention eliminates the use of commas in names is not seen as restrictive. The comma is not recorded as part of the descriptive material.

The name portion and the descriptive material are each limited to 2047 bytes. The name portion may contain up to 14 dots {"."}. Directory structures may have more than 14 dots but only 15 levels are available through the registry key.

DIRECTORY is a key to a named sequence record collection that is the root of this directory structure.

"Key" is the key that is to be recorded.

Return codes

c = 0 success

c = 1 name not unique

c = 2 name name contains illegal characters

c = 3 name is too long

c = 4 no room in directory for new name

c = 5 internal error

c = 6 descriptive material too long

REGISTRY(1,(key name,descriptive material);DIRECTORY,key ==> c;key1) Add or Replace the key and descriptive material for the named key.
"key name" is a character string with embedded dots ".". The name must not contain any wild card designators.

"Descriptive material" is a string of bytes that begins with a ",".

DIRECTORY is a key to a named sequence record collection that is the root of this directory structure.

"Key" is the key that is to be recorded.

"key1" is the key replaced.

Return codes

c = 0 success

c = 1 Key replaced

c = 2 name contains illegal characters

c = 3 name is too long

c = 4 no room in directory for new name

c = 5 internal error

c = 6 descriptive material too long

REGISTRY(2,(key name);DIRECTORY ==> c,(keyname1,descriptive material);key) Return key and descriptive material for named key.
"key name" is a character string with embedded dots ".". The name may contain wild card designators, in which case the key returned is for the first name satisfying the wild card criteria found in the search. The search is done from the top of the tree down. At each level with a wild card specified, the first {alphabetically} name that satisfies the wild card is used.

DIRECTORY is a key to a named sequence record collection that is the root of this directory structure.

"Keyname1" is the name of the key returned. If no wild cards were specified "keyname1" will be the same as "key name".

"Descriptive material" is a string of bytes separated from the keyname1 by a ",".

"key" is the named key.

Return codes

c = 0 success

c = 1 name not found

c = 2 name contains illegal characters

c = 3 name is too long

c = 8 name is found. Wild cards were expanded and more names may be found. Use order code 3 for more names.

REGISTRY(3,(key name,keyname1);DIRECTORY ==>
c,(keyname2,descriptive material);key) Return key and descriptive material for named key {which contains wild cards}, returning the key for the name "after" "keyname1" in the search.
"key name" is a character string perhaps with embedded dots ".". The name must contain wild card designators.

"keyname1" is the last name returned as part of a wild card request sequence, and is separated from key name by a ",".

DIRECTORY is a key to a named sequence record collection that is the root of this directory structure.

"keyname2" is the name of the returned key. The search is from the bottom. The next name that satisfies the wild card designation at the lowest wild card level is located. If none is available, the search continues up the tree to the next higher wild card level. Once a new name is located that satisfies the wild card criterion, the search goes back down the tree using the first name found at each lower wild card level.

"Descriptive material" is a string of bytes separated from the key name by a ",".

"key1" is the returned key.

Return codes

c = 0 success

c = 1 name not found

c = 2 name contains illegal characters

c = 3 name is too long

c = 4 keyname1 contains illegal characters

c = 5 keyname1 is too long

c = 6 keyname1 inconsistent with wild card designators of "key name".

c = 7 second name missing

c = 8 name is found. Wild cards were expanded and more names may be found. Use order code 3 for more names.

REGISTRY(4,(key name);DIRECTORY ==> c;key) Delete a name and return the key.
"key name" is a character string with embedded dots. The name may contain wild card designators, in which case all names meeting the wild card designation are deleted.

DIRECTORY is a key to a named sequence record collection that is the root of this directory structure.

"key" is the key named. No key is returned if "key name" contained wild card designators.

If the name deleted is the last of a directory level, then the directory level is also deleted {recursively until the last name is deleted, the highest level directory is never deleted}.

If it is desired to share substructures within a registry, then a dummy name must be kept in the structure or the REGISTRY key must be of the non-dissolving type.

The registry may be of the non-dissolving type, in which case only the key name specified will be deleted .

If "key name" contains wild cards, no key is returned.

Return codes

c = 0 success

c = 1 name not found or all names satisfying the wild cards are deleted. No key is returned.

c = 2 illegal characters in name

c = 3 name too long

REGISTRY(5,(key name,keyname2);DIRECTORY ==> c) Rename the key designated by key name to keyname2. The descriptive material is copied.
"key name" is the name of the key to be renamed. It must not contain wild card designators.

"keyname2" is the new name. It must not contain wild card designators.

DIRECTORY is a key to a named sequence record collection that is the root of this directory structure.

A directory level may be renamed.

Return codes

c = 0 success

c = 1 name not found

c = 2 name contains illegal characters

c = 3 name is too long

c = 4 keyname2 contains illegal characters

c = 5 keyname2 is too long

c = 6 keyname2 is not unique

REGISTRY(6,(key name);DIRECTORY ==> c,(keyname,descriptive material);KEY) Retrieve the last name that satisfies the wild card specification in keyname.
"key name" is a name with wild cards.

"keyname" is the name that is the last name in the search sequence that satisfies the wild card designation specified in "key name".

DIRECTJT+@Z.Xkey to a named sequence record collection that is the root of this directory structure.

"Descriptive material" is a string of bytes separated from the keyname1 by a ",".

"key" is the named key.

Return codes

c = 0 success

c = 1 name not found

c = 2 name contains illegal characters

c = 3 name is too long

c = 8 name is found. Wild cards were expanded and more names may exist.

REGISTRY(kt,==>029)