NLSAvailable(3nw)

NLSAvailable -- provides information about license units available for products in one or all licensing systems

Synopsis

   LS_STATUS_CODE NLSAvailable( 
      LS_STR          licenseSystem, 
      LS_STR          serverName, 
      LS_STR          publisher, 
      LS_STR          product, 
      LS_STR          version, 
      LS_ULONG         maxStrLen, 
      LS_STR          availablePublisher, 
      LS_STR          availableProduct, 
      LS_STR          availableVersion, 
      LS_LICENSE_ID    availableLicID, 
      LS_ULONG        availableUnits, 
      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 is returned from all licensing systems accessible from this client.
serverName: (IN) Points to th server that contains the license certificate database needed to search for the specified products. It should be the distinguished name 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.
availablePublisher: (OUT) Points to the publisher name for which available units are returned. The product is completely described by a combination of availablePublisher, availableProduct, and availableVersion.
availableProduct: (OUT) Points to the product name for which the available units are returned.
availableVersion: (OUT) Points to the version for which the available units are returned.
availableLicID: (OUT) Returns the unique identifier/serial number of the license certificate from which the information was obtained, within the specific publisher, product, and version domain.
availableUnits: (OUT) Points to the number of available license units at the time the function was called. This does not necessarily indicate the number of installed instances of a product, because availableUnits might represent something else based on the application's licensing policy. Also, this takes into account the current connection status of the user calling NLSAvailable. If the certificate is not available, availableUnits is zero. When used in combination with NLSInUse and NLSInstalled, 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

NLSAvailable 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 NLSAvailable 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.

If the license certificate has security restrictions associated with it (assignments, and so on), the number of units available to a non-security-equivalent object is always zero.