NLSUsers(3nw)

NLSUsers -- provides information about who or what is using licensing units for a product, in the specified licensing systems

Synopsis

   LS_STATUS_CODE NLSUsers( 
      LS_STR          licenseSystem, 
      LS_STR          serverName, 
      LS_STR          publisher, 
      LS_STR          product, 
      LS_STR          version, 
      LS_ULONG         maxStrLen, 
      LS_STR          publisherInUse, 
      LS_STR          productInUse, 
      LS_STR          versionInUse, 
      LS_LICENSE_ID    licIDInUse, 
      LS_ULONG        unitsInUse, 
      LS_STR          user, 
      LS_ULONG        index);

Description

The parameters are as follows:

licenseSystemi: (IN) Points to the licensing systems to search for the specified products. It can either be the specific name of a licensing system, as returned by LSEnumProviders, or it can be LS_ANY. If LS_ANY is specified, information from all installed licensing systems on this client is returned.
serverName: (IN) Points to the server that contains the license certificate database needed to search for the specified products. It should be the DN of the server, or LS_ANY. If LS_ANY is specified, information from all LSPs registered in the Directory tree (from the current context to the root) is returned.
publisher: (IN) Points to the publisher name to filter by. Only transactions that have this publisher name are returned. LS_ANY indicates that any publisher name can appear in the returned entry.
product: (IN) Points to the product name to filter by. Only transactions that have this product name are returned. LS_ANY indicates that any product name can appear in the returned entry.
version: (IN) Points to the version string to filter by. Only transactions that have this version string are returned. LS_ANY indicates that any version string can appear in the returned entry.
maxStrLen: (IN) Specifies the maximum length (in bytes) of string output that can be placed into availablePublisher, availableProduct, and availableVersion. If any of these output strings is longer than maxStrLen, LS_BUFFER_TOO_SMALL is returned.
publisherInUse: (OUT) Points to the name of the publisher for which usage information is being returned. Note that to uniquely identify a product, the publisherInUse, productInUse, and versionInUse must all be utilized.
productInUse: (OUT) Points to the name of the product for which usage information is being returned.
versionInUse: (OUT) Points to the version string for which usage information is being returned.
licIDInUse: (OUT) Returns the unique identifier/serial number (within the specified publisher, product, version domain) of the license certificate from which this information was retrieved.
unitsInUse: (OUT) Points to the current number of units that are in use for the returned publisherInUse, productInUse, and versionInUse. If LS_ANY was specified for licenseSystem, this number potentially crosses licensing systems. This value is not necessarily the number of installed instances of a product, because units might represent something else based on the application's licensing policy. Also, this takes into account the current connection status of the user calling NLSInstalled. If the certificate is not available, numInstalledUnits is zero. When used in combination with NLSInUse and NLSAvailable, this condition can be easily detected.
user: (OUT) Points to the DN of the user who is using license units of the returned product.
index: (IN/OUT) Used to iterate through the entire list of publisher/product/version combinations that are currently in use. index should be initialized to zero on the first call to the function, then opaquely passed back into the function on successive calls. To retrieve all information, continue this process until LS_BAD_INDEX is returned.

Return values

This function returns a detailed error code that can be directly processed by the caller, or that can be converted by LSGetMessage to one of these message strings:

LS_SUCCESS: The requested functionality completed successfully.
LS_SYSTEM_UNAVAILABLE: DOS TSR or Windows DLL is not properly configured or available, or client has no licensing system to communicate with.
LS_BAD INDEX: Index does not point to a valid license certificate. This usually occurs when the end of the requested information has been completely returned.
LS_BAD_ARG: One or more parameters are invalid.
LS_BUFFER_TOO_SMALL: The maxStrLen parameter did not indicate a buffer large enough to hold one of the requested output parameters.

Notices

NLSUsers provides information about who or what is using licensing resources for a product and how many license units are being used by this person/object for one or all licensing systems. The returned information is based on the filtering specified by licenseSystem, publisher, product, and version, on a certificate-by-certificate basis.

On the first call to this function, index should be initialized to zero. A single call to this function returns a single user/object for one product. Subsequent calls either return another user for the same product or the next product if there are no more users/objects. To retrieve this additional information, make another call opaquely passing back index. If the filtering is changed, the index parameter should be reset to zero to get all the information relating to the newly specified parameters. When LS_BAD_INDEX is returned, all information relating to the specified parameters has been returned.