Restrictions for search and update requests

This section describes the restrictions which the HCD LDAP backend imposes on the search, add, delete and modify capabilities of LDAP. Many of these restrictions derive from the fact that the structure of HCD portion of the DIT is much more rigidly controlled than, for instance, the TDBM subtree.

In the following subsections, suffix stands for the suffix of the HCD LDAP backend.

Search

Searching is restricted as follows:

• Only search bases ending with hcdIodfId=Iodf_dataset_name,suffix are supported. This implies that only one IODF can be searched at a time.
• The only search filters that are supported by the HCD LDAP backend are objectclass=* and objectclass=name, where name has to be the name of an object class that is defined for the HCD LDAP backend.
• Time or size limits are not supported.
• Controls are not supported.
• It is not possible to restrict the attributes of the matching entries that will be displayed. Every attribute that has at least one value will be shown in the search results.

Examples: 

Following are two examples for retrieving information from an existing IODF with the command line search utility of LDAP.

The command

ldapsearch -D "racfid=TEST,profiletype=user,sysplex=sysplex1" -w "passwd"
-s base -b "hcdIodfId=TEST.IODF00.WORK,suffix" "objectclass=hcdIodf"

retrieves the top entry of object class hcdIodf belonging to the IODF named TEST.IODF00.WORK on behalf of user ID TEST. The result may look as follows:

hcdIodfId=TEST.IODF00.WORK,suffix
objectClass=hcdIodf
hcdIodfId=TEST.IODF00.WORK
hcdIodfType=W
hcdIodfDescription=Testing purposes
hcdBlocksAllocated=20
hcdBlocksUsed=2
hcdCreationDate=1999-10-04
hcdLastUpdateDate=1999-12-16
hcdLastUpdateTime=09:25:50
1 matches

The same result could be obtained with the search filter "objectclass=*".

The command

ldapsearch -D "racfid=TEST,profiletype=user,sysplex=sysplex1" -w "passwd"
-s one -b "hcdIodfId=TEST.IODF00.WORK,suffix" "objectclass=hcdDevice"

retrieves all entries of object class hcdDevice belonging to the IODF named TEST.IODF00.WORK, again on behalf of user ID TEST. One of the retrieved entries may look as follows:

hcdDeviceNumber=000D,hcdIodfId=TEST.IODF00.WORK,suffix
objectClass=hcdDevice
hcdDeviceNumber=000D
hcdUnit=2540P
hcdModel=1
hcdDescription=Virt. Puncher

Add

Adding an entry is restricted as follows:

• Entries can only be added below hcdIodfId=...,suffix, that is, add is not supported on DN hcdIodfId=...,suffix or DN suffix.
• Since every object class of the HCD LDAP backend except hcdIodf has a uniquely determined parent class, ensure that the object class of the new entry and that of the entry to which the new entry is appended are related as child and parent. Exactly one value must be specified for the objectclass attribute. See Appendix F. IODF data model for parent-child relationships between object classes.
• If the RDN of the entry to be added is attribute=value, value must be specified as a value of attribute inside the entry.
• The attributes which are contained in the entry's RDN are determined by the object class of an entry. See Appendix F. IODF data model.
• There must be no entry in the DIT with the same DN as the entry to be added.
• If an add request fails because of a missing parent, the HCD LDAP backend does not update the matched DN field of the result.
• Check Appendix F. IODF data model to see which object classes can be added.
• Adding an entry may cause other entries to be created automatically using default values. See Appendix F. IODF data model.
• Two controls are supported for the LDAP add request. See Transactions for details.

Example: 

A new entry of the object class hcdControlUnit of type 3990 with a control unit number of 0100 can be appended to the entry hcdIodfId=TEST.IODF00.WORK,suffix as follows.

First create a data set member named TEST.LDIF(ADDCU100) with the content

dn:hcdControlUnitNumber=0100,hcdIodfId=TEST.IODF00.WORK,suffix
changetype:add
objectclass:hcdControlUnit
hcdControlUnitNumber:0100
hcdUnit:3990

Then call the LDAP command line utility ldapadd with the following parameters:

ldapadd -D "racfid=TEST,profiletype=user,sysplex=sysplex1" -w "passwd"
-f //'TEST.LDIF(ADDCU100)'

The entry will be added on behalf of the user ID TEST.

You can then verify that the entry was created correctly by issuing

ldapsearch -D "racfid=TEST,profiletype=user,sysplex=sysplex1" -w "passwd"
-s base -b "hcdControlUnitNumber=0100,hcdIodfId=TEST.IODF00.WORK,suffix"
"objectclass=*"

The search result should look like:

hcdcontrolunitnumber=0100,hcdIodfId=TEST.IODF00.WORK,suffix
objectclass=hcdControlUnit
hcdcontrolunitnumber=0100
hcdunit=3990
1 matches

Delete

Deleting an entry is restricted as follows:

• Only entries below DN hcdIodfId=...,suffix can be deleted. Delete on DN hcdIodfId=..., suffix or DN suffix is not supported.
• Check Appendix F. IODF data model to see which object classes can be deleted.
• Deleting one entry may cause other entries to be deleted automatically. See Appendix F. IODF data model.
• Two controls are supported for the LDAP delete request. See Transactions for details.

Example: 

To delete the entry added in the example shown in Add you can call the LDAP command line utility ldapdelete with the following parameters:

ldapdelete -D "racfid=TEST,profiletype=user,sysplex=sysplex1" -w "passwd"
"hcdControlUnitNumber=0100,hcdIodfId=TEST.IODF00.WORK,suffix"

The entry will be deleted on behalf of the user ID TEST.

Modify

Modifying an entry is restricted as follows:

• Only the entry DN hcdIodfId=...,suffix and below can be modified. Modification of DN suffix is not supported.
• Check Appendix F. IODF data model to see which object classes can be modified.
• The HCD LDAP backend only supports the delete and replace subcommands of modify. The add subcommand is NOT supported.
• The value of the object class attribute cannot be deleted or replaced.
• The value(s) of the attributes which are contained in the entry's RDN cannot be deleted or replaced.
• One modify request to a single entry can contain a sequence of delete and replace subcommands. This sequence can be considered as atomic: Either the whole sequence is performed or nothing is performed.
• One attribute can only be referenced once in the whole modify request. It can only be deleted once, replaced once, and only either be deleted or replaced.
• Modify delete only supports the deletion of all values of an attribute. For this reason, you must not specify values in the modify delete request. If a value is specified, the whole modify request is rejected by the HCD LDAP backend.
• Attributes described as mandatory in an object class must not be deleted
• Modify replace replaces all existing values of the given attribute with the new values listed, creating the attribute if it did not already exist. A replace with no value will delete the entire attribute if it exists, and is ignored if the attribute did not exist.
• All values must conform with the type specified in the attribute definition.
• Modifying an entry may cause other entries to be modified automatically. See Appendix F. IODF data model.
• Two controls are supported for the LDAP modify request. See Transactions for details.

Example: 

The entry created in Add can be modified by adding the attribute hcdDescription as follows.

First create a data set member named TEST.LDIF(REPCU100) with the content

dn:hcdControlUnitNumber=0100,hcdIodfId=TEST.IODF00.WORK,suffix
changetype:modify
replace:x
hcdDescription:New description

Then call the LDAP command line utility ldapmodify with the following parameters:

ldapmodify -D "racfid=TEST,profiletype=user,sysplex=sysplex1" -w "passwd"
-f //'TEST.LDIF(REPCU100)'

If the modify request completes successfully, the entry will look like:

hcdControlUnitNumber=0100,hcdIodfId=TEST.IODF00.WORK,suffix
objectClass=hcdControlUnit
hcdControlUnitNumber=0100
hcdUnit=3990
hcdDescription=New description

This hcdDescription can now be deleted again with the delete subrequest of modify. To do this, first create a data set member named TEST.LDIF(DELCU100) with the content

dn:hcdControlUnitNumber=0100,hcdIodfId=TEST.IODF00.WORK,suffix
changetype:modify
delete:hcdDescription
-

Then issue the following command:

ldapmodify -D "racfid=TEST,profiletype=user,sysplex=sysplex1" -w "passwd"
-f //'TEST.LDIF(DELCU100)'