Reference

Web Registry Functions

A Web registry is a file with a key maintained by Net.Data to allow you to add, retrieve, and delete entries easily. You can create multiple Net.Data Web registries on a single system. Each registry has a name and can contain multiple entries. Net.Data provides functions to maintain registries and the entries they contain.

DTWR_ADDENTRY
DTWR_CLEARREG
DTWR_CLOSEREG
DTWR_CREATEREG
DTWR_DELENTRY
DTWR_DELREG
DTWR_LISTREG
DTWR_LISTSUB
DTWR_OPENREG
DTWR_RTVENTRY
DTWR_UPDATEENTRY

Restrictions:

Do not use asterisks (*) for the registry, registryVariable, and registryData parameters when using OS/2.
Each parameter passed to a Web Registry function is limited to a maximum of 2048 characters.

DTWR_ADDENTRY

AIX	HP-UX	Linux	OS/2	OS/390	OS/400	SCO	SUN	Win NT
X			X		X			X

Purpose

Adds an entry to a Web registry.

Format

@DTWR_ADDENTRY(registry, registryVariable, registryData, index)

@DTWR_ADDENTRY(registry, registryVariable, registryData)

Parameters

Table 187. DTWR_ADDENTRY Parameters

Data Type	Parameter	Use	Description
string	`registry`	IN	The name of the registry to which the entry is added.
string	`registryVariable`	IN	The value of the `registryVariable` string portion of the registry entry to add.
string	`registryData`	IN	The value of the `registryData` string portion of the registry entry to add.
string	`index`	IN	The value of the index portion of the `registryVariable` string in an indexed entry to add. This parameter is optional. If specified, an indexed entry is added to the specified registry.

Return Codes

Table 188. DTWR_ADDENTRY Return Codes

Return Code	Explanation
-1001	The server could not process a Net.Data request to allocate memory.
1001	An input parameter contained a NULL value.
1002	An input parameter contained a string value which consisted of the null-terminating character.
1003	The number of parameters passed on a function call either exceeded the maximum number allowed, or was less than the minimum number required by the function.
1005	A parameter passed on a function call, required to be a string variable, was of a different variable type.
1007	A parameter contains a value which is not valid.
3003	A Web registry built-in function could not add an entry to the specified registry because the specified entry already exists.
3005	A Web registry built-in function could not use the specified registry because it cannot be found.
3006	A Web registry built-in function could not create the specified registry because a path in the registry name does not exist.
3007	A Web registry built-in function could not complete the specified operation because the requestor does not have the proper authority to the specified registry.

Examples

Example 1:

@DTWR_ADDENTRY("Myregistry", "Jones", "http://Advantis.com/~Jones/webproj")

Example 2:

@DTWR_ADDENTRY("URLLIST", "SMITH", "http://www.software.ibm.com/",
     "WORK_URL,")

DTWR_CLEARREG

AIX	HP-UX	Linux	OS/2	OS/390	OS/400	SCO	SUN	Win NT
X			X		X			X

Purpose

Clears entries from a Web registry.

Format

@DTWR_CLEARREG(registry)

Parameters

Table 189. DTWR_CLEARREG Parameters

Data Type	Parameter	Use	Description
string	`registry`	IN	The name of the registry to clear.

Return Codes

Table 190. DTWR_CLEARREG Return Codes

Return Code	Explanation
-1001	The server could not process a Net.Data request to allocate memory.
1001	An input parameter contained a NULL value.
1002	An input parameter contained a string value which consisted of the null-terminating character.
1003	The number of parameters passed on a function call either exceeded the maximum number allowed, or was less than the minimum number required by the function.
1005	A parameter passed on a function call, required to be a string variable, was of a different variable type.
1007	A parameter contains a value which is not valid.
3005	A Web registry built-in function could not use the specified registry because it cannot be found.
3006	A Web registry built-in function could not create the specified registry because a path in the registry name does not exist.
3007	A Web registry built-in function could not complete the specified operation because the requestor does not have the proper authority to the specified registry.

Examples

Example 1:

@DTWR_CLEARREG("Myregistry")

DTWR_CLOSEREG

AIX	HP-UX	Linux	OS/2	OS/390	OS/400	SCO	SUN	Win NT
					X

Purpose

Closes a Web registry

Format

@DTWR_CLOSEREG(registry)

Parameters

Table 191. DTWR_CLOSEREG Parameters

Data Type	Parameter	Use	Description
string	`registry`	IN	The name of the registry to close. Restriction: Do not use special characters such as the asterisk (*) and the backslash (\) in Web registry names.

Return Codes

Table 192. DTWR_CLOSEREG Return Codes

Return Code	Explanation
-1001	The server could not process a Net.Data request to allocate memory.
1001	An input parameter contained a NULL value.
1002	An input parameter contained a string value which consisted of the null-terminating character.
1003	The number of parameters passed on a function call either exceeded the maximum number allowed, or was less than the minimum number required by the function.
1005	A parameter passed on a function call, required to be a string variable, was of a different variable type.
1007	A parameter contains a value which is not valid.
3005	A Web registry built-in function could not use the specified registry because it cannot be found.

Examples

Example 1: Close a registry

@DTWR_CLOSEREG("/qsys.lib/mylib.lib/myreg.file")

DTWR_CREATEREG

AIX	HP-UX	Linux	OS/2	OS/390	OS/400	SCO	SUN	Win NT
X			X		X			X

Purpose

Creates a new Web registry.

Format

@DTWR_CREATEREG(registry, security)

@DTWR_CREATEREG(registry)

Parameters

Table 193. DTWR_CREATEREG Parameters

Data Type	Parameter	Use	Description
string	`registry`	IN	The name of the registry to create. Restriction: Do not use special characters such as the asterisk (*) and the backslash (\) in Web registry names.
string	`security`	IN	The type of security with which to create `registry`. On UNIX operating systems, the default security is the same as the directory where the registry is created. Specify security for the three security groups: user, group, and public. R gives read permission, W gives write permission, and X give execute permission. For example, to give all three groups full authority, specify `RWX, RWX, *RWX` for this parameter. This parameter it optional.

Return Codes

Table 194. DTWR_CREATEREG Return Codes

Return Code	Explanation
-1001	The server could not process a Net.Data request to allocate memory.
1001	An input parameter contained a NULL value.
1002	An input parameter contained a string value which consisted of the null-terminating character.
1003	The number of parameters passed on a function call either exceeded the maximum number allowed, or was less than the minimum number required by the function.
1005	A parameter passed on a function call, required to be a string variable, was of a different variable type.
1007	A parameter contains a value which is not valid.
3002	A Web registry built-in function could not delete the specified registry.
3006	A Web registry built-in function could not create the specified registry because a path in the registry name does not exist.
3007	A Web registry built-in function could not complete the specified operation because the requestor does not have the proper authority to the specified registry.
3008	A Web registry built-in function could not create the specified registry for unknown reasons.

Examples

Example 1:

@DTWR_CREATEREG("myRegistry")

Example 2:

@DTWR_CREATEREG("URLLIST", "*RWX, *RWX, *R")

DTWR_DELENTRY

AIX	HP-UX	Linux	OS/2	OS/390	OS/400	SCO	SUN	Win NT
X			X		X			X

Purpose

Deletes an entry from a Web registry.

Format

@DTWR_DELENTRY(registry, registryVariable, index)

@DTWR_DELENTRY(registry, registryVariable)

Parameters

Table 195. DTWR_DELENTRY Parameters

Data Type	Parameter	Use	Description
string	`registry`	IN	The name of the registry from which the entry is removed.
string	`registryVariable`	IN	The value of the `registryVariable` string portion of the entry to remove.
string	`index`	IN	The value of the index portion of the `registryVariable` string in an indexed entry. This is an optional parameter. If specified, the indexed entry is removed from the registry.

Return Codes

Table 196. DTWF_DELENTRY Return Codes

Return Code	Explanation
-1001	The server could not process a Net.Data request to allocate memory.
1001	An input parameter contained a NULL value.
1002	An input parameter contained a string value which consisted of the null-terminating character.
1003	The number of parameters passed on a function call either exceeded the maximum number allowed, or was less than the minimum number required by the function.
1005	A parameter passed on a function call, required to be a string variable, was of a different variable type.
1007	A parameter contains a value which is not valid.
3004	A Web registry built-in function could not remove or retrieve an entry from the specified registry because the specified entry does not exist.
3005	A Web registry built-in function could not use the specified registry because it cannot be found.
3007	A Web registry built-in function could not complete the specified operation because the requestor does not have the proper authority to the specified registry.

Examples

Example 1:

@DTWR_DELENTRY("Myregistry", "Jones")

Example 2:

@DTWR_DELENTRY("URLLIST", "SMITH", "WORK_URL")

DTWR_DELREG

AIX	HP-UX	Linux	OS/2	OS/390	OS/400	SCO	SUN	Win NT
X			X		X			X

Purpose

Deletes a Web registry

Format

@DTWR_DELREG(registry)

Parameters

Table 197. DTWR_DELREG Parameters

Data Type	Parameter	Use	Description
string	`registry`	IN	The name of the registry to delete.

Return Codes

Table 198. DTWR_DELREG Return Codes

Return Code	Explanation
-1001	The server could not process a Net.Data request to allocate memory.
1001	An input parameter contained a NULL value.
1002	An input parameter contained a string value which consisted of the null-terminating character.
1003	The number of parameters passed on a function call either exceeded the maximum number allowed, or was less than the minimum number required by the function.
1005	A parameter passed on a function call, required to be a string variable, was of a different variable type.
1007	A parameter contains a value which is not valid.
3005	A Web registry built-in function could not use the specified registry because it cannot be found.
3007	A Web registry built-in function could not complete the specified operation because the requestor does not have the proper authority to the specified registry.

Examples

Example 1:

@DTWR_DELREG("Myregistry")

DTWR_LISTREG

AIX	HP-UX	Linux	OS/2	OS/390	OS/400	SCO	SUN	Win NT
X			X		X			X

Purpose

Lists the contents of a Web registry.

Format

@DTWR_LISTREG(registry, registryTable)

Parameters

Table 199. DTWR_LISTREG Parameters

Data Type	Parameter	Use	Description
string	`registry`	IN	The name of the registry to list.
table	`registryTable`	OUT	The name of the table variable in which the registry entries are placed.

Return Codes

Table 200. DTWR_LISTREG Return Codes

Return Code	Explanation
-1001	The server could not process a Net.Data request to allocate memory.
1001	An input parameter contained a NULL value.
1002	An input parameter contained a string value which consisted of the null-terminating character.
1003	The number of parameters passed on a function call either exceeded the maximum number allowed, or was less than the minimum number required by the function.
1004	A parameter passed on a function call, required to be a Net.Data macro table variable, was of a different variable type.
1005	A parameter passed on a function call, required to be a string variable, was of a different variable type.
1006	A literal string was passed on a function call for a parameter which was required to be an output parameter.
1007	A parameter contains a value which is not valid.
3005	A Web registry built-in function could not use the specified registry because it cannot be found.
3007	A Web registry built-in function could not complete the specified operation because the requestor does not have the proper authority to the specified registry.

Usage Notes

DTWR_LISTREG returns information about the registry entries in an OUT table variable passed by the user. The table variable is defined in the user macro before being passed as a parameter to the FUNCTION block for the LISTREG registry operation.

If the user defined the table variable using the ALL option for the maximum number of rows for the table, this operation lists all available registry entries in the table, one for each table row. On the other hand if the user specified a value X for the maximum number of table rows, then if there are more then X entries in the specified registry only the first X entries are listed and an error code is sent back to indicate that only a partial listing could be done because not enough table rows were available to list additional entries. All registry entries are listed if the value X exceeds the number of available entries in the specified registry.

There are always 2 columns in the table. The Column headers for the table are set to REGISTRY_VARIABLE and REGISTRY_DATA.

Examples

Example 1:

%DEFINE RegistryTable = %TABLE(ALL)
 
@DTWR_LISTREG("URLLIST", RegistryTable)

DTWR_LISTSUB

AIX	HP-UX	Linux	OS/2	OS/390	OS/400	SCO	SUN	Win NT
								X

Purpose

Lists immediate subkey entries in a Web registry.

Format

@DTWR_LISTSUB(registry, registryTable)

Parameters

Table 201. DTWR_LISTSUB Parameters

Data Type	Parameter	Use	Description
string	`registry`	IN	The name of the registry to list.
table	`registryTable`	OUT	The name of the table variable in which the registry entries are placed.

Return Codes

Table 202. DTWR_LISTSUB Return Codes

Return Code	Explanation
-1001	The server could not process a Net.Data request to allocate memory.
1001	An input parameter contained a NULL value.
1002	An input parameter contained a string value which consisted of the null-terminating character.
1003	The number of parameters passed on a function call either exceeded the maximum number allowed, or was less than the minimum number required by the function.
1005	A parameter passed on a function call, required to be a string variable, was of a different variable type.
1006	A literal string was passed on a function call for a parameter which was required to be an output parameter.
1007	A parameter contains a value which is not valid.
3005	A Web registry built-in function could not use the specified registry because it cannot be found.
3007	A Web registry built-in function could not complete the specified operation because the requestor does not have the proper authority to the specified registry.

Usage Notes

DTWR_LISTSUB returns information about the registry entries in an OUT table parameter passed by the user. The table variable is defined in the macro before being passed as a parameter to the LISTSUB registry operation.
If the user has defined the table variable using the ALL option for the maximum number of rows for the table, this operation lists all available registry entries in the table, one for each table row. On the other hand, if the user specified a value X for the maximum number of table rows then if there are more then X entries in the specified registry only the first X entries are listed and an error code is sent back to indicate that only a partial listing could be done because not enough table rows are available to list additional entries. All registry entries are listed if the value X exceeds the number of available entries in the specified registry. The number of columns in the table is always one.
The column header for the table is set to "REGISTRY_SUBKEY".
This function is only valid on operating system that are compatible Windows 95 System Registries.

Examples

Example 1:

%DEFINE RegistryTable = %TABLE(ALL)
 
@DTWR_LISTSUB("URLLIST", RegistryTable)

DTWR_OPENREG

AIX	HP-UX	Linux	OS/2	OS/390	OS/400	SCO	SUN	Win NT
					X

Purpose

Opens a Web registry.

Format

@DTWR_OPENREG(registry, commit)

@DTWR_OPENREG(registry)

Parameters

Table 203. DTWR_OPENREG Parameters

Data Type	Parameter	Use	Description
string	`registry`	IN	The name of the registry to open.
string	`commit`	IN	A single symbol or literal string specifying whether the registry is opened under commitment control or not. The possible values are: Y Open the registry under commitment control. N Do not open the registry under commitment control. The default is N

Return Codes

Table 204. DTWR_OPENREG Return Codes

Return Code	Explanation
-1001	The server could not process a Net.Data request to allocate memory.
1001	An input parameter contained a NULL value.
1002	An input parameter contained a string value which consisted of the null-terminating character.
1003	The number of parameters passed on a function call either exceeded the maximum number allowed, or was less than the minimum number required by the function.
1005	A parameter passed on a function call, required to be a string variable, was of a different variable type.
1007	A parameter contains a value which is not valid.
3005	A Web registry built-in function could not use the specified registry because it cannot be found.
3007	A Web registry built-in function could not complete the specified operation because the requestor does not have the proper authority to the specified registry.

Examples

Example 1: Open the registry under commitment control

@DTWR_OPENREG("/qsys.lib/mylib.lib/myreg.file", "Y")

DTWR_RTVENTRY

AIX	HP-UX	Linux	OS/2	OS/390	OS/400	SCO	SUN	Win NT
X			X		X			X

Purpose

Retrieves a registry string value from a Web registry.

Format

@DTWR_RTVENTRY(registry, registryVariable, registryData, index)

@DTWR_RTVENTRY(registry, registryVariable, registryData)

@DTWR_rRTVENTRY(registry, registryVariable, index)

@DTWR_rRTVENTRY(registry, registryVariable)

Parameters

Table 205. DTWR_RTVENTRY Parameters

Data Type	Parameter	Use	Description
string	`registry`	IN	The name of the registry with entries to retrieve.
string	`registryVariable`	IN	The value of the `registryVariable` string portion of the registry entry whose registryData string is retrieved.
string	`registryData`	OUT	Returns the value of the `registryData` string portion of the registry entry that matches the `registryVariable`.
string	`index`	IN	The value of the index portion of the `registryVariable` string in an indexed entry whose `registryData` string is returned. This is an optional parameter. If specified, the `registryData` string of the indexed entry is returned.

Return Codes

Table 206. DTWR_RTVENTRY Return Codes

Return Code	Explanation
-1001	The server could not process a Net.Data request to allocate memory.
1001	An input parameter contained a NULL value.
1002	An input parameter contained a string value which consisted of the null-terminating character.
1003	The number of parameters passed on a function call either exceeded the maximum number allowed, or was less than the minimum number required by the function.
1005	A parameter passed on a function call, required to be a string variable, was of a different variable type.
1006	A literal string was passed on a function call for a parameter which was required to be an output parameter.
1007	A parameter contains a value which is not valid.
3004	A Web registry built-in function could not remove or retrieve an entry from the specified registry because the specified entry does not exist.
3005	A Web registry built-in function could not use the specified registry because it cannot be found.
3007	A Web registry built-in function could not complete the specified operation because the requestor does not have the proper authority to the specified registry.

Examples

Example 1:

%DEFINE RegistryData = ""
@DTWR_RTVENTRY("Myregistry", "Jones", RegistryData)

Example 2:

@DTWR_RTVENTRY("URLLIST", "SMITH", RegistryData, "WORK_URL")

Example 3:

@DTWR_rRTVENTRY("Myregistry", "Jones")

Example 4:

@DTWR_rRTVENTRY("URLLIST", "SMITH", "WORK_URL")

DTWR_UPDATEENTRY

AIX	HP-UX	Linux	OS/2	OS/390	OS/400	SCO	SUN	Win NT
X			X		X			X

Purpose

Updates a registry string value in the Web registry.

Format

@DTWR_UPDATEENTRY(registry, registryVariable, newData, index)

@DTWR_UPDATEENTRY(registry, registryVariable, newData)

Parameters

Table 207. DTWR_UPDATEENTRY Parameters

Data Type	Parameter	Use	Description
string	`registry`	IN	The name of the registry with the entry to update.
string	`registryVariable`	IN	The value of the `registryVariable` string portion of the registry entry to update.
string	`newData`	IN	The new value for the `registryData` string portion of the registry entry to update.
string	`index`	IN	The value of the index portion of the `registryVariable` string in an indexed entry to update. This is an optional parameter. If specified, the indexed entry is updated.

Return Codes

Table 208. DTWR_UPDATEENTRY Return Codes

Return Code	Explanation
-1001	The server could not process a Net.Data request to allocate memory.
1001	An input parameter contained a NULL value.
1002	An input parameter contained a string value which consisted of the null-terminating character.
1003	The number of parameters passed on a function call either exceeded the maximum number allowed, or was less than the minimum number required by the function.
1005	A parameter passed on a function call, required to be a string variable, was of a different variable type.
1007	A parameter contains a value which is not valid.
3003	A Web registry built-in function could not add an entry to the specified registry because the specified entry already exists.
3004	A Web registry built-in function could not remove or retrieve an entry from the specified registry because the specified entry does not exist.
3005	A Web registry built-in function could not use the specified registry because it cannot be found.
3007	A Web registry built-in function could not complete the specified operation because the requestor does not have the proper authority to the specified registry.

Usage Notes

The registry entry name corresponding to the value cannot be changed.

Examples

Example 1:

@DTWR_UPDATEENTRY("Myregistry", "Jones", "http://advantis.com/~Jones/personal")

Example 2:

@DTWR_UPDATEENTRY("URLLIST", "SMITH", "http://www.software.ibm.com/personal", "WORK_URL")

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]