NLSInUse(3nw)

NLSInUse -- provides information about license units that are in use for products in one or all licensing systems

Synopsis

   LS_STATUS_CODE NLSInUse( 
      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        numUnitsInUse, 
      LS_ULONG        index);

Description

The parameters are as follows:

licenseSystem: (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.
numUnitsInUse: (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.
index: (IN/OUT) Used to iterate through the entire list of publisher/product/version combinations that are currently available. 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

NLSInUse provides information about the number of license units available for products in one or all licensing systems, based on the filtering specified by licenseSystem, publisher, product, and version, on a certificate-by-certificate basis.

When NLSInUse is first called, index should be initialized to zero. A single call to this function returns the availability of units for one certificate. To get information for other certificates, call NLSAvailable again with index reset to zero to obtain all the information relating to the newly specified parameters. When LS_BAD_INDEX is returned by NLSAvailable, all information relating to the specified filtering parameters has been returned.