Secondary Sections

A simple Files section could be:

These commands cause that all files of the directory 'p:\install\instnsc\netscape' are copied to the directory C:\netscape, and then all files from p:\install\instnsc\windows to the windows system directory (its value is automatically inserted into the constant name %SYSTEMROOT%). Option -s means that all subdirectories are copied as well, -V activates the version control for library files.

In most cases a Files section will be called without parameters.

There are only some special uses of Files sections where the target of copy actions is set or changed in a certain specified way. We have got the two optional parameters

Both variants mean:
The called Files section is executed once for each local user. Every copy command in the section is associated with an user specific target directory.

In case other we need to build other user specific path names we can use the automatically set variable %UserProfileDir% or since opsi-script version 4.11.2 %CurrentProfileDir%. With option /AllUserProfiles (resp. /AllNTUserProfiles) the user specific target directory for copy actions is the user profile directory (that is usually denoted by the username and is by default situated as a subdirectory of the userappdata directory. In case of option /AllNTUserSendTo the target directory is the path of the user specific 'SendTo' folder (for links of the windows explorer context menu).

The exact rule for determining the target path for a copy command has three parts:

The use of %CurrentProfileDir% has the advantage that you may the same 'Files' section with /AllUserProfiles if it is not running as 'userLoginScript' (in 'Machine' script mode) and without /AllUserProfiles if it is running as 'userLoginScript' (in 'Login' script mode).

There are also the Options:

which manipulate the 'file redirection' on 64 Bit systems. For more details see opsi-script-64bit

In a Files section the following commands are defined:

Copy and Delete roughly correspond the the Windows shell commands xcopy resp. del.

SourcePath and CheckTargetPath set origin and destination of the forthcoming copy actions (as if we would open two explorer windows for copy actions between them). If the target path does not exist it will be created.

The syntax definitions are:

or

Possible options are (with arbitrary ordering)

Example (you may forget the trailing Backslash):
del -sf c:\delete_this_dir

zipfile <source dir> <zip file> // since 4.12.1 [W/L/M]

unzipfile <zip file> <target dir> [<encoding>]// since 4.12.1 [W/L/M]

Example:

Since version 4.12.13, zipfile per default uses 'utf8' for encoding filenames with umlauts. This is for ZIP archives the recommended encoding for umlauts in filenames.

Since version 4.12.13, unzipfile per default unzips archives containing files with umlauts in the filenames with correctly encoded filenames. According to the ZIP specification, only codepage 'cp437' or 'utf8' is permitted as encoding for file names with umlauts. If the zip archive complies with the specification and uses 'cp437' or 'utf8' for file name encoding, this will be recognized by default during unpacking and the umlauts are set correctly in the file names of the unpacked files. But not all ZIP archives follow the specification and might use a different encoding for the file names. If unzipfile does not correctly generate file names with umlauts, version 4.12.13 provides an optional third parameter, to specify the encoding of the file names in the archive:

unzipfile <zip file> <target dir> [<encoding>] // since 4.12.13 [W/L/M]

Example:

This example specifies, that the filenames inside testfile.zip are encoded in codepage 'cp850'. In this case unzipfile will convert the filenames from 'cp850' to system codepage.

For allowed encodings see opsi-script encoding

In very rare cases the archive filenames could be using different encodings. In that case the archive has to be repacked with 'utf8' encoded filenames. For instance by using the program '7zip', which can unzip archives with mixed filename encodings and then zip again as 'utf8'.

produces the following log:

For more examples, please check the opsi standard product 'opsi-script-test' and in this product the part '$Flag_winst_patches$ = "on"'

The name of the file to be patched is passed as a parameter.

There are optional modifiers:

For allowed encodings see opsi-script encoding

For a Patches section, we have commands:

Each command refers to some section of the file which is to be patched. The name of this section is specified in brackets [] (which do here not mean "syntactically optional"!!).

In detail:

The text file which is to be treated is given as parameter.

There are optional modifiers:

For allowed encodings see opsi-script encoding

We have got two commands especially for patching Mozilla preferences files plus the two deprecated and more restricted older versions of these commands:

The other commands of 'PatchTextFile' sections are not file type specific. All operations are based on the concept that a line pointer exists which can be moved from top of the file i.e. above the top line down to the bottom (line).

There are three search commands:

Each command starts searching at the current position of the line pointer. If they find a matching line the line pointer is moved to it. Otherwise the line pointer keeps its position.
The search is not case sensitive.

<search string> - as all other String references in the following commands - are String surrounded by single or double citation marks.

(when we count lines it has to be noted that this commands move the line pointer above the top line). We step any - positive or negative - number of lines through the file by

By the following command :

For more examples, please check the opsi standard product 'opsi-script-test' and in this product the part '$Flag_winst_patch_text_file$ = "on"'

E.g. the following section creates a folder named "acrobat“ in the common start menu (shared by all users):

In a 'LinkFolder' section first must be defined, in which virtual system folder the subsequent instructions are to operate. This expression defines the base folder:
set_basefolder '<virtual system folder>'

Virtual system folders to be used are:

'desktop, sendto, startmenu, startup, programs, desktopdirectory, common_startmenu, common_programs, common_startup, common_desktopdirectory'

These folders are virtual, for it depends on the operating system (and version), what the resulting physical directory name is.

In the context of standard 'maschine' installations, only the virtual system folders starting with common_ are relevant.

The system folders 'desktop, sendto, startmenu, startup, programs, desktopdirectory' can only be used in the context of a logged on user respectively in a 'userLoginScript' in the context of the opsi extension 'user Profile Management'.

The folders are 'virtual' since the operating system (resp. registry entries) determine the real places of them in the file system. Second, we have to open a subfolder of the selected virtual folder:
set_subfolder <folder path>
The subfolder name is to be interpreted as a path name with the selected virtual system folder as root. If some link shall be directly placed into the system folder we have to write
set_subfolder ""

In the third step, we can start setting links. The command is a multi line expression starting with
set_link
and finished by end_link.

Between these lines the link parameters are defined in the following format:

set_link
name: [link name]
target: <complete program path>
parameters: [command line parameters of the program]
working_dir: [working directory]
icon_file: [icon file path]
icon_index: [position of the icon in the icon file]
shortcut: [keyboard shortcut for calling the target]
end_link

The 'target' name is the only essential entry. The other entries have default values:

produces the following log:

For more examples, please check the opsi standard product 'opsi-script-test' and in this product the part '$Flag_winst_link_folder$ = "on"'.

LinkFolder sections are supported also on Linux since version 4.11.5.2.

Possible bas folders are:
common_programs,common_autostart,desktop, autostart
Subfolder is always "" (empty).

The Link Option icon_index is ignored.
As additional Link Option we have: link_categories.
Here you may use the following values seperated and terminated by a semicolon:
AudioVideo, Audio, Video, Development, Education, Game, Graphics, Network, Office, Settings, System, Utility
The LinkFolder Sektion will work at Linux with different Desktop systems

Let’s have a look at a simple xml file:

To describe the structure in this xml file we use the following wording:

The name of the file to be patched is passed as a parameter.

Example:
xml2_test "%scriptpath%\dummy.xml"

If the given file does not exist, it will be created. While creating the file as name of the root node, we use the value of the command rootNodeOnCreate = <node name>. If this command is missing in the section, the fall back is the root node name: 'rootnode'. (since 4.12.4.27)

There are optional modifiers:

For allowed encodings see opsi-script encoding

The idea of the syntax here is based on the command syntax of other patch sections like registry or patches in opsi-script.

There exist the following commands:

In detail:

The first step is to navigate to the node where we like to change things.

The <xml2 path> is the path to our target node.
It may have two different forms, according to the value of 'strictMode':

All other commands operate on an opened xml node.

Example:

We assume we have a file dummy.xml with the content:

The following code:

produces e.g the log:

The following code:

produces e.g the log:

For further examples see the product 'opsi-script-test' expecially the file sub-scripts/xml2test.opsiscript

When calling an XMLPatch section the document path name is given as parameter, e.g.
XMLPatch_mozilla_mimetypes $mozillaprofilepath$ + "\mimetypes.rdf"

A XML document logically describes a "tree" which starting from a "root" - therefore named document root– grows into branches. Every branch is labelled a node. The sub nodes of some node are called children or child nodes of their parent node.

In XML, the tree is constructed from elements. The beginning of any element description is marked by a tag (similarly as in HTML) i.e. a specific piece of text which is set into a pair of angle brackets ("<“ ">“, The end of the element description is defined by the the same tag text but now bracket by "</“ and „>“. If an element has no subordinated elements then there is no space needed between start tag and end tag. In this case the two tags can be combined to one with end bracket "/>“.

This sketch shows a simple "V"-tree - just one branching at the root level, rotated so that the root is top: _~~ | root node (level 0) / \ node 1 and node 2 both on level 1 . . implicitly given end nodes below level 1 _~~ This tree could be described in XML in the following way:

The first line has to declare the XML version used. The rest of lines describe the tree.

So long the structure seems to be simple. But yet we have only "main nodes" each defining an element of the tree and marked by a pair of tags. But each main node may have subnodes of several kinds.

Of course, an element may have subordered elements, e.g. we may have subnodes A to C of node 1:

If there are no subordinated elements an element can have subordinated text. Then it is said that the element has a subordinated text node. Example

A line break placed in the text node is now interpreted as part of the text where otherwise it is only a means of displaying XML structure. To avoid a line break belonging to "hello world" we have to write

Every element (no matter if it has subordinated elements or subordinated text) is constituted as a main node with specific tags. It can be further specified by attributes, so called attribute nodes. For example, there may be attributes "colour" or "angle" that distinguish different nodes of level 1.

For selecting a set of elements any kind of information can be used:

In opsi-script, selection based on criteria (1) to (3) and (7) is implemented

Before any operation on the contents of a XML file the precise set of elements has to be determined on which it will be operated. The set is constructed step by step by defining the allowed paths through the XML tree. The finally remaining end points of the paths define the selected set.

The basic opsi-script command is

There two formats for defining the allowed paths a short and a long format .

The more explicit syntax may be seen in the following example (for a more complex example cookbook-patchxml):

The same node set is given by the line:

In this syntax, the slash separates the steps into to the tree structure which are denoted in the more explicit syntax each by an own description.

Given the explicit syntax we may select elements by the textual content of elements:

In the exemplary descriptions of XML tree traversals there remain several questions.

To answer these questions explicitly there are parameters for the OpenNodeSet command. The following lines show the default settings which can be varied by changing the Boolean values:

With short syntax, parametrizing precedes the OpenNodeSet command and holds for all levels of the XML tree. With the explicit syntax the parameters may be set directly after the OpenNodeSet command or be newly set for each level. In particular the option „create when node not existing“ may be set for some levels but not for all.

There exists a bundle of commands which operate on a selected element set

In detail:

On the contrary, the command

By
* DeleteAttribute "attribute name"
we remove the specified attribute from each element of the selected element set.

The command
* DeleteElement "element name"
removes all elements with main node name (tag name) element name from the opened element set.

Finally there exist two commands for setting resp. adding text nodes.:

and

Example:
SetText "rtf"
transforms the element
'<fileExtensions>doc<fileExtensions>'
into
'<fileExtensions>rtf<fileExtensions>'

By
SetText ""
we remove the text node completely.

The variant
AddText "rtf"
sets the text only if there was no text node given.

A XMLPatch section may return the retrieved informations to the calling primary section. The result always is a String list, and to get it, the call must done via the String list function getReturnListFromSection. E.g. we may have the following String list setting in an Actions section where we use a XMLPatch_mime section

Inside the XMLPatch section we have return commands that determine the content of returned String list:

For further examples see the product 'opsi-script-test' expecially the sector with '$Flag_winst_xml$ = "on"'

There a several parameters of the WinBatch call which determine if (or how long) opsi-script shall be wait for the started programs returning.

Explanation:
When starting an external process from a winbatch call, the opsi-script waits for the current process to finish before executing the next command in the script.

Example:

There are some external programs which start another process and then end without waiting for their child process to end. From the point of view of opsi-script, the process is ended and the next command could be started.

If you run an uninstall program and a setup program in sequence and the uninstall program works with such a child process, you can have conflicting processes running because the uninstallation and installation processes are running at the same time.

Using the modifier /WaitForProcessEnding helps to avoid such a situation.

The first option means that opsi-script waits until any process lets pop up a window with title [window title]. With the second option opsi-script is waiting as long as a certain window (1) appeared on the desktop and (2) disappeared again.
CAUTION: These options only know windows of 32-bit programms

For further examples see the product 'opsi-script-test' expecially the sector with '$Flag_winst_winbatch$ = "on"'

There are two kinds of parameters which may be passed to the section call:

The calling syntax is:

Sektionsname [batch parameter] [winst [modifier]]

Possible opsi-script modifier are (since 4.11.1):

*/encoding <encoding> //since 4.12.4.17 [W/L/M]
By default the content of the section will be stored to a temporary file in system encoding. This is in the most cases the best choice. If you really knows what you are doing, you may change the encoding of the stored temporary file:
You can add an encoding parameter after the WINST keyword.
Example :

For allowed encodings see opsi-script encoding

Since 4.12.4.0 the following modifiers may be used that are well known from winbatch sections and are explained over there: Call Parameter (Modifier)

These opsi-script modifier have to be separated by the key word winst from the other parameters.

Other parameters of a ShellScript section are directly passed as quasi command line parameters to the Windows shell script.
For example, we may call ShellScript_1 in Actions section to get a "Hello World" from the DOS echo command:

the execution of the Dos-Batch command echo with parameters 'today we say "Hello World"'.

The next example will be on a 64 bit system executed in a 64 bit cmd.exe and gives the output 'today we say':

Since Version 4.11.5 not only string constants but also string variables are allowed as parameters (but no string functions)

Example:

Code from opsi-script-test:

produce the log:

The output of the shell commands can be captured by using the string list function getOutStreamFromSection() from the opsi-script-scripts main-section see also:
Simple String Values generated from String Lists or Files).

If the return list shall be evaluated programmatically it is advised to use the '@' prefix of commands. Such we suppress the repetition of the command line in the output which may different formats dependent on system configurations.

For further examples see the product 'opsi-script-test' and there look at '$Flag_winst_dos$ = "on"'

Let us set some registry variables by a call to the section Registry_TestPatch where the section is given by

For further examples see the product 'opsi-script-test' and there look at '$Flag_subregistry$ = "on"'

Further parameters control which syntactical variant of the Registry section shall be valid:

These not opsi-script specific syntactical variants are not defined in this manual since they usually will be generated programmatically.

There are also the Options:

which manipulate the 'registry write redirection' on 64 Bit systems. (see opsi-script-64bit).

The default syntax of a Registry section is oriented at the command syntax of other patch operations in opsi-script.

There exist the following commands:

In detail:

The registry key is denoted by a registry path name. Under regular circumstances it starts with one of the "high keys" which build the top level of the registry tree data structure (above the "root" ). These are: 'HKEY_CLASSES_ROOT, HKEY_CURRENT_USER, HKEY_LOCAL_MACHINE, HKEY_USERS, HKEY_CURRENT_CONFIG' which may optionally be written as 'HKCR, HKCU, HKLM, HKU'.

In opsi-script syntax of the registry path name, the elements of a path are separated by single backslashs.

All other commands operate on an opened registry key.

The empty variable "" denotes the standard entry of a registry key.

If some registry variable shall be created or set where the data type should be explicitly given, we have to use the extended variant of the Set command:

To construct a multistring we may put the strings as lines in a file and read it using GetMultiSZFromFile (cf. below).

Example for set with different registry data types:

Example:
The environment Path is determined by the value for the variable Path as defined inside the registry key

+ 'KEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\Environment'

+ To add some entries to the path definition we have to get access to this key via an OpenKey. Then we can apply e.g.

+ supp "Path" ; "C:\utils;%JAVABIN%"

+ in order to supplement the path by '"C:\utils"' and '"%JAVABIN%"'.

+ (Windows expands %JAVABIN% to the correct path name if %JAVABIN% exists as variable and the String is a REG_EXPAND_SZ.)

+ Whom read the old value of Path from the environment variable, write this value to the registry value - and are then able to work with the registry variable:

+

A Registry section called with parameter /AllNTUserdats is executed for every local user.

To this end, for all local users (as permanent storage for the registry branch 'HKEY_Users') the files 'NTUser.dat' are searched one by one and temporarily loaded into a subkey of some registry branch. The commands of the registry section are executed for this subkey, then the subkey is unloaded. As result, the stored 'NTUser.dat' is changed.

The mechanism does not work for a logged in user. For, his 'NTUser.dat' is already in use, and the request to load it produces an error. To do the changes for him as well, the commands of the Registry additionally are executed on the 'HKEY_Users' branch for the logged in user.

There is a 'NTUser.dat' for 'Default User' which serves as template for newly created users in the future. Therefore the patches are prepared for them as well.

The Registry section syntax remains unchanged. But the key pathes are interpreted relatively. This means leave away the main key

In the following example the registry entry for variable 'FileTransferEnabled' is de facto set for all 'HKEY_Users\XX\Software…​' successive for all XX (all users) on the machine:

Since opsi-script version 4.11.2 you may give the root key 'HKEY_CURRENT_USER' at the openkey command.
Example:

This has the folloing advantages:

If a Registry section is called with parameter /regedit the section is not expected in opsi-script standard format but in the format as produced by the Windows regedit tool. The export files generated by regedit have - not regarding the head line - ini file format. Example:

The sections denote registry keys to be opened. Each line describes some variable setting like the set command in a opsi-script registry section.

But, we cannot really have an internal opsi-script section that is constructed from another sections. Therefore Registry section with parameter /regedit can only be given as external section or by the function call loadTextFile, e.g.

With Windows XP the registry editor regedit does not produce Regedit4-Format but a new format that is indicated by the head line
'"Windows Registry Editor Version 5.00"'

In this format, Windows offers some additional value types. But more important, the export file is now generated in Unicode. opsi-script sections processing is based on Delphi libraries which use 8 bit Strings. To work with a regedit 5 export the coding therefore has to converted. This can be done manually, e.g. by a suitable editor. But we may also feed the original file to opsi-script using the String list function loadUnicodeTextFile. E.g., if printerconnections.reg be a unicode based export, we can call regedit in the following form which does the necessary code conversion on the fly:

A registry patch using regedit format can as well be executed "for all NT users" similarly as the common opsi-script registry section. That is, a path like '[HKEY_CURRENT_USER\Software\ORL]' is to replaced by the relative '[Software\ORL].'

A Registry section can be called with parameter /addReg. Then its syntax follows the principles of the '[AddReg]' sections in inf files as used e.g. for driver installations.

E.g.:

The call parameters that change the standard connection:

Restore of the original connection:

With the opsiServiceCall section with a parameter call /preloginservice the standard connection will be restore to the previous value. Alternatively one can also make a call to the statement without an actual existing section:
opsiServiceCall /preloginservice

The parameter call:

The call parameters determine which opsi service will be addressed and set the connection parameters if needed.

Connection parameters can be defined via

If these parameters are defined (or at least one of them), an attempt is made to connect to the mentioned service URL and, if successful, then this will be the default connection.

The additional option

raises an interactive connect. The user will be asked for confirming the connection data and supplying the password. Of course, this option cannot be used in scripts which shall be executed fully automatically.

If no connection parameters are supplied opsi-script assumes that an existing connection shall be reused.

If no connection parameters are given and the interactive option is not specified (neither at this call nor at a call earlier in the script) it is assumed that we are in a standard opsi boot process and, already having a connection to an opsi service, we try to address it.

An opsiServiceCall, which uses an existing connection to an opsi-service, is defined by its method name and a list of parameters.

Both are defined in the section body. It has format

The line "timeout":<seconds> is optional.
It is only needed by calling methods that run very long (> 90 seconds). It is available since 4.12.4.35.

'<params>' is a (possibly empty) list of strings (comma-seperated). Since opsi 4.12.4.37 it is also possible to write the following values in '<params>' without quotation marks (as in JSON syntax): numbers, boolean values, arrays, objects and null. Use the parameters as required by the specified method.

E.g. we may have a section call where the required methodname and the (empty) list of parameters is set:

The section call produces the list of names (IDs) of all local opsi clients. If the list shall be exploited for other than test purposes the section call can be used in a string list expression: E.g.:

The usage of GetReturnListFromSection is documented in the string list function chapter of this manual (see opsi-script-stringlist-create-by-section).

A hash – in this case a string list, where each item is a pair name=value – is produced by the following opsi service call:

Dealing with JSON objects from the web service requires a basic understanding of JSON, the opsi objects and the JSON-related methods in opsi-script. See also: Opsi-manual: Chapter: "Web service / API methods since opsi 4.0" :
https://download.uib.de/opsi4.2/stable/documentation/html/en/opsi-manual-v4.2/opsi-manual-v4.2.html#opsi-manual-api-datastructure-opsi4

In the code shown below, you can get objects from the service. In this example, all productOnClient objects that belong to the current computer will be retrieved (% opsiserviceUser% are in the service context of the FGDN of the client) and are localboot products, by which the action request is set to 'setup'.

The result is a JSON Array String which is in the first line of $resultlist$.

You can also restore (changed) objects. The following example clarifies the principle: The string variable $ArrayStr$ must contain a valid JSON array.

For further examples watch the product 'opsi-script-test' an there especially '$Flag_winst_opsiServiceCall$ = "on"'

An execPython section is integrated with the surrounding opsi-script script by four kinds of shared data:

An example for the first two ways of interweaving the python script with the opsi-script script is already given above. We extend it to retrieve the values of some opsi-script constants or variables.

Of course, the '$loglevel$' variable has to be set beforehand in the Actions section:

Finally, in order to being able to use of some results of the section output, we produce it into a stringlist variable by calling the execPython section in the following way:

For further examples watch the product 'opsi-script-test' and there especially '$Flag_compare_to_python$ = "on"'

In general, we have the call syntax:

Each of the expressions 'PROGRAM, PROGRAMPARAS, PASSPARAS, WINSTOPTS' may be an arbitrary String expression, or just a String constant (without citation marks).

The key words PASS and WINST may be missing if the respective parts do not exist.

The following opsi-script-options are available:

Like with ExecPython sections, the output of an ExecWith section may be captured into a String list via the function getOutStreamFromSection.

The first one declares that the backslash in opsi-script variables and constants is C-like escaped. The second one has the effect (as for 'WinBatch' calls) that the called program starts its work in a new thread while opsi-script is continuing to interpret its script.

Since Version 4.11.3.5, if the interpreter path contains 'powershell.exe', the temporary file is saved with the extension .ps1.

Notes on PowerShell

The following call is meant to refer to a section which is an autoit3 script that waits for some upcoming window (therefore the option /letThemGo is used) in order to close it:

A simple

calls notepad and opens the section lines in it (but without any line that is starting with a semicolon since opsi-script regards such lines as comments and eliminates them before handle).

The following example call the 64Bit version of the powershell.exe.

For further examples watch the product 'opsi-script-test' and there especially '$Flag_autoit3_test$ = "on"'.

LDAP, the "Lightweight Directory Access Protocol", is, as the name indicates, a defined way of communication to a directory. This directory is (or may be) hierarchically organized. That is, the directory is a hierarchical data base, or a tree of content.

A LDAP service implements the protocol. A directory that can be accessed via a LDAP service is called a LDAP directory.

For instance, let’s have a look at some part of the LDAP directory tree of an opsi server with LDAP backend (as shown by the Open Source tool JXplorer):

A LDAP search request is a query to a LDAP directory via a LDAP service. The response returns some content from the directory.

Basically the search request has to describe the path in the directory tree which leads to the interesting piece of information. The path is the distinguished name (dn), composed of the names of the nodes (the "relative distinguished names"), which build the path, for instance:

'local/uib/opsi/generalConfigs/bonifax.uib.local'

Since each node is conceived as an instance of some structural object class, the path description is usually given in the following form: with indication of the classes (and starting with the last path element) :

'cn=bonifax.uib.local,cn=generalConfigs,cn=opsi,dc=uib,dc=local'

The path in a query is not necessarily "complete", and not leading to a unique leaf of the tree. On the contrary, partial paths are common.

But even if the path descends to a unique leaf, the leaf may contain several values. Each node of the tree has one or more classes as attribute types. To each one or may values may be associated.

For a given query path, we therefore may be interested

Obviously, handling the amount of possibly returned response information is the main challenge when dealing with LDAP searches.

The following section shows the documentation of a LDAPsearch roughly corresponding to the screenshot above as executed by opsi-script.

Example

Using the opsi-script section ldapsearch_generalConfigs:

we will get a answer like this:

There are several opsi-script options to manage and reduce the complexity of the evaluation of such responses.

Two kinds of LDAPsearch parameters,

are defined for the call of LDAPsearch section.

The 'cache options' are:

If there is no cache option specified, the response of the LDAP search request is not saved for further usages.

By the /cache option, the response is cached for further evaluations, the /cached option refers to the last cached response which is reused instead of starting a new search, the /free option clears the cache explicitly (may only be useful for searches with extreme large responses).

The 'output options' are:

The output options determine the String list that is produced when a LDAPsearch section is called via getReturnlistFromSection:

Observe that in the produced lists the object an attribute belongs to is only identifiable if only one object is returned in the object list, and likewise the object and the attribute to which a value is subsumed are only identifiable if there is only attribute remaining in the attributes list.

Such the proceeding is, that the LDAPsearch is specified up to that degree, that at most one object and one attribute is returned. This can be checked by a count call on the objects and the attributes return list. Then any value found belongs to the dn and the attribute specified.

The repeated utilization of the same LDAP response can be done without relevant time costs by using the cache/cached options.

An example may show how we can narrow the search to pin down a specific result from a LDAP directory.

We start with the call of 'ldapsearch_generalConfigs' as above, only adding the cache parameter.

ldapsearch_generalconfigs /cache

executes the query and caches the response for further utilization.

Then, the call

getReturnlistFromSection("ldapsearch_generalconfigs /cached /objects")

produces the list

If we narrow the tree selection by

and start again, then in the objects list, we indeed retain just

The corresponding attributes list contains three elements:

In order to get the values associated to a single attribute we have to confine the query once more:

The result now produced is an attributes list containing only one element. The corresponding values list looks like

There are no LDAP means to reduce this result furthermore!

(But the opsi-script function getValue (key, list) (cf. Simple String Values generated from String Lists or Files) may help in this case: E.g.
getValue ("secsuntilconnectiontimeout", list)
would produces the requested number).

By the function count (list) we can check if we succeeded with the narrowing of the search request. In most circumstances, we would like that its result be "1".

A LDAPsearch section comprises the specifications:

A short and rather realistic example shall end this section:

'$founditems$' be a StringList variable and '$opsiClient$' a String variable. The call of 'getReturnlistFromSection' fetches the results of the section 'ldapsearch_hosts'. The following code fragment returns the unique result for $opsiDescription$ if it exists. It reports an error if the search produces an unexpected result:

Example with user / password

For further examples watch the product 'opsi-script-test' and there especially '$Flag_winst_ldap_search$ = "on"'