Home

FLEXlm Reference Manual

1. SEE ALSO e Section 7 3 5 LM_A CHECK INTERVAL e Section 7 3 16 LM_A_RETRY_COUNT LM_A_RETRY_INTERVAL e Section 7 3 18 LM_A_USER_EXITCALL LM_A_USER_EXITCALL_EX e Section 7 3 19 LM_A_USER_RECONNECT LM_A_USER_RECONNECT_EX 220 Heartbeats Manual Heartbeats e Section 7 3 20 LM_A_USER_RECONNECT_DONE LM_A_USER_RECONNECT_DONE_EX e Section 8 2 11 LM_A_MT_HEARTBEAT UNIX Only 12 2 Manual Heartbeats Manual heartbeats are used instead of automatic heartbeats if the application e Wants to be in control of the precise timing of heartbeats e Cannot tolerate the extra thread introduced by automatic heartbeats e Cannot be multithreaded e Can be interrupted only at specific times Some applications have critical sections of code that cannot be interrupted Manual heartbeats provide a way for the application to control when the heartbeat thread executes thereby not perturbing the critical sections To set up manual heartbeats the application needs to 1 Turn off the automatic heartbeat timer before a license is checked out For the FLEXible API Set both the LM_A_CHECK_INTERVAL and LM_A_RETRY_INTERVAL attribute to 1 as follows lc_set_attr lm_job LM_A_CHECK_INTERVAL LM_A_VAL_TYPE 1 lc_set_attr lm_job LM_A_RETRY_INTERVAL LM_A_VAL_TYPE 1 For Trivial or Simple Use the LM_MANUAL_HEARTBEAT policy m
2. Feature f1 can be used on any Sparc station running Solaris Feature f2 can be used on a Windows or HP system There is one license that can be shared between all Windows and HP systems and one license just for Windows That is at most one f2 can be used on the HP systems and at most two f2 s can be used on Windows systems If the checkout fails because it s on the wrong platform the error returned is LM_PLATNOTLIC This platform not authorized by license SEE ALSO e Section 8 2 14 LM_A PLATFORM OVERRIDE FLEX m Release Notes located in the machina directory of the FLEX m SDK 3 5 17 SIGN SIGN signature Required field Signature for this FEATURE line signature is from 12 20 characters long and is produced by Ic_cryptstr in Imcrypt or makekey or by a vendor defined utility that calls lc_crypstr When using lmcrypt put SIGN 0 at the end of each FEATURE line and lmcrypt will replace the 0 with the correct signature 3 5 18 SN 46 SN serial_num Optional field Useful for differentiating otherwise identical INCREMENT lines Its only use by FLEX m is to be encrypted in the signature Similar to HOSTID The License File Syntax FEATURE INCREMENT Lines 3 5 19 START START dd mmm yyyy Optional field Feature start date If the license is used before this date the checkout fails with LM_TOOEARLY 3 5 20 SUITE DUP_GROUP Note 3 5 21 S
3. e If LM_LICENSE_FILE is a license file list colon separated on UNIX and semi colon separated on Windows with more than one license server supporting features for the client and 1f the application needs to check out more than one feature it may be necessary to communicate with two license servers to check out the necessary licenses This can be done only with multiple jobs because a separate connection is required for each server It may be convenient to have a single process manage licenses for other processes It is usually convenient to manage each process s license as a separate job e Ic_checkin checks in all licenses for a given feature name If the application needs to check in only some of the licenses this can be done with multiple jobs where groups of checkouts are done in separate jobs and checked in separately from each job The first item can be important as an alternative way of supporting license server redundancy Following is a program excerpt that illustrates how to support this LM_HANDLE job1 0 job2 0 VENDORCODE code if lc_new_job LM_HANDLE 0 lc_new_job_arg2 amp code amp job1 error processing set_all_my_attr jobl do all necessary lc_set_attr calls if 1c_checkout job1 f1 1 0 1 LM_CO_NOWAIT code LM_DUP_NONE error processing We checkout out one feature successfully so we re connected to a server already I
4. 14 LM_BADHOST 15 LM_CANTCONNECT E Error Number Table invalid returned data from license server The port number returned from lmgrd is invalid An attempted connection to a vendor daemon did not result in a correct acknowledgment from the daemon The daemon did not send back a message within the timeout interval A message from the daemon had an invalid checksum An Ic_userlist request did not receive the correct data no SERVER lines in license file There is no SERVER line in the license file All non zero license count features need at least one SERVER line cannot find SERVER hostname in network database The gethostbyname system call failed for the SERVER name in the license file Cannot connect to license server The connect system call failed while attempting to connect to the daemon The attempt to connect to the vendor daemon on all SERVER nodes was unsuccessful Ic_status returns LM_CANTCONNECT if the feature had been checked out but the program is in the process of reconnecting If reconnection fails the final status return is LM_CANTCONNECT FLEXIm Reference Manual August 2004 279 Error Number Table 16 LM_CANTREAD 17 LM_CANTWRITE 18 LM_NOSERVSUPP 19 LM_SELECTERR 20 LM_SERVBUSY 21 LM_OLDVER 22 LM_CHECKINBAD cannot read data from license server The process cannot read data fro
5. 299 D 4 2 FEATURESET Line errara o EEEE 00 00 cee 302 D 4 3 Intel Pentium III Hostid HOSTID_INTEL 303 Index Sewanee deme ata chases a ene ios 305 FLEXIm Reference Manual August 2004 xi xii FLEXIm Reference Manual August 2004 000000005 Preface About This Manual This manual the FLEXIm Reference Manual provides a comprehensive reference to the advanced features of FLEX m from the software developer s perspective including a complete description of three application programming interfaces e Trivial API used with single process applications that checkout just one feature It is provided in two formats macro based and function based e Simple API used with applications that require checking out more than one feature or license at a time e FLEXible API the most complete API available for license management All documentation is provided online in the htmlman directory and can be accessed through any HTML browser Product Information FLEX m is a software licensing package that allows licensing a software application on a concurrent usage as well as on a per computer basis FLEX m allows the implementation of a wide variety of license policies by the developer of an application With FLEX m you the application developer can restrict the use of your software packages to a e Single specified computer e Specified number of users on a network of one or more computer systems FLEX m is
6. Reference Manual VERSION 9 5 AUGUST 2004 ma rovision COPYRIGHT NOTICE O 2003 2004 Macrovision All rights reserved Macrovision products contain certain confidential information of Macrovision Use of this copyright notice is precautionary and does not imply publication or disclosure No part of this publication may be reproduced transmitted transcribed stored in a retrieval system or translated into any language in any form by any means without the written permission of Macrovision TRADEMARKS Globetrotter Macrovision FLEX m FLEXlock FLEXbill Flexible License Manager and GTlicensing are registered trademarks or trademarks of Macrovision Corporation All other brand and product names mentioned herein are the trademarks and registered trademarks of their respective Owners RESTRICTED RIGHTS LEGEND Use duplication or disclosure by the government is subject to restrictions as set forth in subparagraph c 1 ii of the Rights of Technical Data and Computer Software clause of DFARS 252 227 0713 and FAR52 227 19 and or applicable Federal Acquisition Regulation protecting the commercial ownership rights of independently developed commercial software Printed in the USA August 2004 Contents Pretace is tt ti tale e xiii Chapter 1 IntroductiOn s ereo ta it Ei 17 1 1 FLEXI APIS umi tasas a taa a lis 17 1 1 1 Trivial and Simple APIs ooooc oococococcnconoo o 17 11 2 FLEXible APIs
7. amp lm_job lc_perror lm_job lc_init failed exit 1 x_flexlm_newid 7 Open your client application source file in a text editor In this example we are using machind 1lmflex c e Make the 1m_job variable global by moving it before main VENDORCODE code LM_HANDLE 1m_job void main e After the call to lc_new_job add the following line x_flexlm_newid That section should resemble if lc_new_job 0 lc_new_job_arg2 amp code amp lm_job lc_perror lm_job lc_new_job failed exit lc_get_errno lm_job x_flexlm_newid 8 Open plat form makefile in a text editor This example uses a Windows makefile e Add the vendor defined hostid code to the list of EXECS For this example add vendor_hostid obj e After the DAEMON section add a section to build vendor_hostid obj For example vendor_hostid obj SRCDIR vendor_hostid c CC S CFLAGS 1 h SRCDIR vendor_hostid c e Add vendor_hostid obj to the link line for DAEMON makekey lmcrypt and lmflex For example for lmflex exe lmflex exe SRCDIR lmflex c LMNEW_OBJ S CLIENTLIB lmstrip exe CC CFLAGS SRCDIR lmflex c 244 Vendor Defined Hostid Types Test the Vendor Defined Hostid S LD out lmflex exe lmflex obj vendor_hostid obj LMNEW_OBJ S CLIENTLIB XTRALIB if exist lmflex obj del lmflex obj 9 Rebuild your duplicate FLEX m SDK 15 3 Test the Vendor De
8. ls_vendor_msg 0 To add support for sending messages from your client code to the daemon with Ic_vsend initialize 1s_vendor_msg with a pointer to your routine which processes the message and create the reply for the client 1s_vendor_msg is called with a single parameter the character string sent by the client It should create a reply message and return a pointer to it The message string will be unused the next time that 1s_vendor_msg is called so the use of a single static char array in 1s_vendor_msg is appropriate Make sure an object file with this routine is linked with your vendor daemon SEE ALSO e Section 6 4 23 lc_vsend FLEXIm Reference Manual August 2004 233 Vendor Variables 234 Vendor Daemon Composite Hostids 14 1 Overview A composite hostid combines FLEX m hostids together to provide a more secure hostid A composite hostid is a hashed 12 character hexidecimal value formed by combining the values of one or more simple hostids types It can be used anywhere a simple hostid is used on a SERVER line or FEATURE line of a license file Incorporating a composite hostid into your license policy involves the following actions e Decide which hostid types are included in your composite hostid e Include code in your FLEX m enabled application to initialize the composite hostid e For served licenses modify your vendor daemon to initialize the composite hostid e Provide a way for your en
9. 75 52 3 O A E Ae aes E an ween TI 5 2 4 Ip h artbetO e irea bce oa Faw Pee E N Oh eal 78 DQ Clpe perro emea dron eir E a E E E EE E ws 79 5 2 6 AA aiai iE eae ee tas 79 52 7 Ipuwarning eene ee eine l naa a ee 80 Chapter 6 ELEXible APL i niea a bad we et 81 6 1 FLEXible API Function Summary 004 81 6 2 FLEXible API Functions by Category 05 83 6 2 1 Checkin and Checkout 0 0 0 2c eee ee eee 83 6 2 2 Job Handling 200 ct eae dash kak bee dea 84 6 2 3 Heartbeat Management and Communication 84 6 2 4 Informational 2 0 0 ken Ee i paa A eee 86 6 2 5 Error and Warning Reporting ooooooocoocoooo 87 6 2 6 License File Installation 0 0 0 88 6 2 7 License File Generation 0 0 0 c eee eee 88 6 3 Commonly Used FLEXible API Functions 89 6 4 FLEXible API Function Descriptions 90 64 1 e putr tt A A eed ok 90 6 42 le checkin ai A ee R 91 AAA tes Ge a Ge hb tes Geta dees 92 64 4 le Cry pista cai Ataris wei i 101 GAS le eri aniOQ ets eh oe ee Sh a oe 107 6 4 6 Ic_errstring 1 eee cece ees 109 FLEXIm Reference Manual August 2004 v Chapter 7 vi 6 4 7 Ic_expire_days ce eee nea a iea eee 110 6 4 8 Ie feat list ii SiGe ds Sedo be aR ORR 2 111 6 4 9 Je first Job acc a tae saga ays 112 GATO WEE Job cias peri Pa ete beers Pa tia beg Hines eg Ske 113
10. It limits license usage to five users on any host with an Internet IP address matching 195 186 and it never expires It must be in a license file with SERVER and VENDOR lines SEE ALso e Chapter 15 Vendor Defined Hostid Types e Section 8 3 9 Is_use_all_feature_lines e Section 13 2 4 Is_compare_vendor_on_increment and ls_compare_vendor_on_upgrade e Section 8 2 5 LM_A_CRYPT_CASE_SENSITIVE Feature Name feature is the name given to the feature by the vendor Legal feature names in FLEX m must contain only letters numbers and underscore characters Letters in the feature name are case insensitive by default If case sensitivity is desired see Section 8 2 10 LM_A_LICENSE_CASE_SENSITIVE Vendor Daemon Name vendor is the vendor daemon name from a VENDOR line This vendor daemon serves this feature Feature Version The feat_versionis the latest highest numbered version of this feature that is supported by this license file The version is in floating point format with a ten character maximum FLEXIm Reference Manual August 2004 41 FEATURE INCREMENT Lines 3 5 4 3 5 5 3 5 6 3 5 7 42 Expiration Date exp_date is the expiration date of the feature in the format dd mmm yyyy permanent For example 22 mar 2005 For no expiration use permanent Use four digits for the year specification A date with a year of 0 is equivalent to permanent 1 jan 0 1 jan
11. License server out of network connections The vendor daemon can t handle any more users See the 1mgra debug log for further information Dongle not attached or can t read dongle In order to read the dongle hostid the correct driver must be installed Missing Dongle Driver In order to read the dongle hostid the correct driver must be installed FLEXlock checkouts attempted Only one checkout is allowed with FLEX ock enabled applications Subsequent checkout attempts will fail They should be disabled if first checkout succeeded in FLEX ock mode SIGN attribute required This is probably because the license is older than the application You need to obtain a SIGN version of this license from your vendor Error in Public Key package Rare error 292 FLEXIm Status Return Values Error Number Table 116 CRO not supported for this LM_NOCROSUPPORT PRE COLA You are trying to use CRO but have not installed CRO keys 117 BORROW failed LM_BORROW_LINGER_ERR Borrowing information is invalid 118 BORROW period has expired LM_BORROW_EXPIRED Borrowed license can no longer be checked out because it has expired 119 Imdown and lmreread must be run LM_MUST_BE_LOCAL eS ee iver mode When licenses are borrowed 1Imdown and lmreread must be run on the same machine where the license server is running 120 Cannot lmdown the server when LM BORROW DOWN licen
12. SERVER Lines ER host hostid port A SERVER line specifies the name and hostid of the license server machine and optionally the TCP IP port number through which to communicate to lmgrd A license file may have one or three SERVER lines The SERVER node name in the license file can be any network alias for the node host String returned by the UNIX hostname or uname n commands or an IP address in HHH HEH HHH HHH format This can be edited by the license administrator IP address is recommended for sites where NIS or DNS have trouble resolving a host name or if the server node has multiple network interfaces and hence multiple host names this _host can be used when the host name is unknown This allows the product to be installed and to start the license server Clients on the same host as the license server will work fine Clients on other nodes will need to set LM_LICENSE_FILE or VENDOR_LICENSE_FILE to port host or host to find the license server or this_host can simply be edited to the real host name Note that lminstall and Ic_convert will automatically change this_host to the real host name when appropriate FLEXIm Reference Manual August 2004 33 SERVER Lines Note hostid port String returned by the imhostid command case insensitive Only one hostid is allowed Alternate special hostids can also be specified here including ANY HOSTNAME host etc See the FLEXIm
13. SYNTAX LM_USERS users users lc_userlist job feature DESCRIPTION Provides a list of who is using the feature including information about the users of the license This output is used by Imstat See the FLEXIm End Users Guide for the behavior of lmstat PARAMETERS LM_HANDLE job From Ic_new_job char feature The feature name The call to Ic_userlist is potentially expensive it may cause a lot of network traffic depending on the number of users of feature Therefore this function must be used with caution In particular it is a good idea to call Ic_userlist when a checkout fails with LM_MAXUSERS LM_USERSQUEUED error to inform who is using the feature However do not call lc_userlist before every call to Ic_checkout because this will be guaranteed to cause network load problems when a large number of licenses are checked out RETURN If successful lc_userlist returns a pointer to a linked list of structures one for each user of the license This data should not be modified by the caller It will be freed on the next call to Ic_userlist See lmclient h for a description of the LM_USERS struct The list of users returned by Ic_userlist includes a special record indicated by an empty user name name 0 0 which contains the total number of licenses supported by the daemon for the specified feature in the nlic field and the daemon s idea of the current time in the t ime field
14. 1 and 2 Expires on January 1 2005 Floating runs on any node No hostid on FEATURE lines Limited to ten concurrent licenses for each feature Mixed Floating Counted and Uncounted SERVER speedy 08002b32b161 VENDOR demo FEATURE f1 demo 2 0 permanent 1 HOSTID 80029a3d SIGN 7B9F02AC0645 INCREMENT f1 demo 2 0 permanent 2 HOSTID 778da45 SIGN 6BAFD2BC1C3D FEATURE 0 demo 2 0 permanent uncounted HOSTID FLEXID 8 12345678 SIGN ABOCCOC16807 Checkouts of f0 since it is uncounted may not communicate with the server they only verify that the client is on node FLEXID 8 12345678 i e the node has the hardware key with id 8 12345678 attached and that the version is lt 2 0 If USE_SERVER is specified or either VENDOR_LICENSE_FILE or LM_LICENSE_FILE is set to Ghost or port host if a port number is specified on the SERVER line then checkouts do require a server and their usage is logged The f0 line does not require the SERVER or VENDOR lines and in fact could reside in another license file altogether The License File Overview 2 4 License in a Buffer License in a Buffer The license file does not need to be located on disk it can be specified in the program itself The license path in CHECKOUT or Ip_checkout can specify the actual license as in this example CHECKOUT LM_RESTRICTIVE f1 1 0 START_LICENSE n FEATURE f1 demo 1 0 permanent uncounte
15. 8 3 9 192 The check performed by 1s_do_checkroot will fail on a diskless node This prevents diskless nodes from acting as license servers Macrovision does not recommend running license daemons on diskless nodes but if you choose to support this you will need to set 1s_do_checkroot to 0 For improved security set 1s_do_checkroot to 1 For minimization of confusion and support calls when your customers are running on diskless nodes set 1s_do_checkroot to 0 Is dump_send_data int ls_dump_send_data 0 Set to non zero value for debug output This variable controls the debug output of transmitted daemon data It should normally be left set to 0 Is hud_hostid_case_sensitive int ls_hud_hostid_case_sensitive 0 This variable controls the case sensitivity for hostid types HOSTNAME DISPLAY and USER in the context of a served node locked license When ls_hud_hostid_case_sensitive is set to 0 the values for HOSTNAME DISPLAY and USER hostids are treated as case insensitive When set to 1 these values are treated as case sensitive The default setting is 0 case insensitive Is_use_all_feature_lines int ls_use_all_feature_lines 0 Use ALL copies of feature lines that are The variable causes your vendor daemon to process every FEATURE line in the license file as an INCREMENT line With 1s_use_all_feature_lines Set to a non zero value any old feature lines which you may
16. FLEXIm Reference Manual August 2004 299 Obsolete License File Features For example FEATURE 2 demo 1 0 permanent uncounted 6E06CC47D2AB HOSTID 1234 MNARAAAAARAMA license key If a vendor daemon or client library is configured to authenticate a license using the license key LM_STRENGTH_LICENSE_KEY those components can authenticate the license using either the 12 or 20 character license key That is a vendor daemon or client library configured for non license key LM_STRENGTH_DEFAULT or LM_STRENGTH_ 133 163 239 BIT will not authenticate the license with either size of license key those components will only authenticate the license using their respective value of the SIGN field The license key is 12 characters by default Previous to v6 license keys are 20 characters they are also referred to as long license keys Both 12 and 20 character license keys are accepted 20 character license keys can be enabled v a one of e lc _set_attr job LM_A_LKEY_LONG LM_A VAL TYPE 1 e lc_set_attr job LM_A_BEHAVIOR_VER LM_A VAL TYPE behavior where behavior is LM_BEHAVIOR_V5_1 or less lt 12 character license keys impact licensing in two ways e Instead of a 64 bit security key on each feature line there s a 48 bit security key e A start date in not embedded in the license key You can specify a start date in two ways e For both 12 and 20 character license keys use the opt
17. Ic_borrow_return SYNTAX status lc_borrow_return job feature display DESCRIPTION Ic_borrow_return is used to return a borrowed license to the pool of available licenses before the borrow period expires The application which calls this routine must be running on the same machine from which the license was originally borrowed In order for this routine to have an effect the license server must be configured to allow early return of borrowed licenses PARAMETERS LM_HANDLE job From Ic_new_job char feature The name of the borrowed feature to be returned early char display The display from which the borrow was initiated Required if the current display is different than what was used to initiate the borrow On Windows it is the system name or in the case of a terminal server environment the terminal server client name On UNIX it is in the form dev ttyxx or the X Display name If NULL FLEX m uses the current display name determined via the standard method appropriate to the platform RETURN int status The FLEX m error code or 0 for no error FLEXIm Reference Manual August 2004 159 Advanced FLEXible API Functions 160 ERROR RETURNS LM_BADPARAM Problem with job or feature argument LM_BORROW_ERROR Cannot read the local borrow info LM_BORROW_RETURN_ The server generated an error during a SERVER_ERR license return attempt LM_CANTCONNECT Cannot connect to license server
18. Windows only Cleans up FLEXIm resources after they are no longer needed Ic_convert Converts a license file from one format to the other Formats include readable and decimal Ic_free_hostid Frees the memory associated with a hostid structure FLEXIm Reference Manual August 2004 157 Advanced FLEXible API Functions 8 1 1 158 Table 8 1 Advanced FLEXible API Functions Continued Function Description Ic_get_config Returns license file data for a given feature Ic_get_errno Returns the most recent FLEX m error Ic_init_simple_composite Initializes a composite hostid Ic_next_conf Returns the next line in the license file matching the given feature Ic_remove Removes a given feature for the specified user Ic_shutdown Shuts down the FLEX m license servers Ic_test_conf Returns license file data for the most recently tested feature _new_hostid SYNTAX hostid 1 _new_hostid DESCRIPTION Returns a malloc d and zeroed hostid Use Ic_free_hostid to free this memory This may be needed when doing vendor defined hostids PARAMETERS None RETURN HOSTID A HOSTID struct or null hostid ERROR RETURNS LM_CANTMALLOC malloc call failed Advanced FLEXible API Features Advanced FLEXible API Functions SEE ALso e Section 7 3 22 LM_A VENDOR_ID_ DECLARE e Chapter 15 Vendor Defined Hostid Types
19. e Section 6 4 20 Ic_set_attr e Section 11 4 Multiple Jobs e Section 13 2 11 Is_show_vendor_def Advanced FLEXible API Features 8 2 3 Note Advanced FLEXible API Attributes LM_A_CHECKOUTFILTER LM_A_CHECKOUTFILTER_EX Type Pointer to a function returning int Default None DESCRIPTION The function pointer LM_A_CHECKOUTFILTER or the extended version LM_A_CHECKOUTFILTER_EX is set to point to a checkout filter callback function This filter function is invoked each time Ic_checkout finds a FEATURE INCREMENT line that is a candidate for fulfilling the license request Candidates are selected based on the feature name This filter provides the application the opportunity to examine the FEATURE INCREMENT line before Ic_checkout processes it and either allows lc_checkout to proceed processing the line or rejects this particular line lc_checkout may still reject the line even though the filter function allows processing to proceed The LM_A_CHECKOUTFILTER routine is called as follows status myCheckoutFilter config or with LM_A_CHECKOUTFILTER_EX status myCheckoutFilterEx job config vendor_data LM_A_CHECKOUTFILTER_EX provides a way to pass vendor defined data to this callback function Behavior is undefined if both LM_A_CHECKOUTFILTER_EX and LM_A_CHECKOUTFILTER are set CALLBACK PARAMETERS LM_HANDLE job LM_A_CHECKOUTFILTER_EX only A pointer to the license job t
20. if 1c_checkout lm_job f1 LM_CO_LOCALTEST error processing else Retrieve information for feature f1 conf lc_test_conf lm_job Display information for feature f1 printf feature s version s daemon s An conf gt feature conf gt version conf gt daemon PARAMETERS LM_HANDLE From Ic_new_job Im_job RETURN CONFIG conf The CONFIG struct or NULL if error The CONFIG struct is defined in the header file Imclient h FLEXIm Reference Manual August 2004 173 Advanced FLEXible API Attributes 8 2 174 ERROR RETURNS No ne SEE ALso lmclient h for the CONFIG struct definition Section 6 4 1 Ic_auth_data Section 6 4 3 Ic_checkout Section 8 1 7 Ic_get_config Section 8 1 10 lc_next_conf Advanced FLEXible API Attributes The attributes in this section provide advanced capabilities beyond what is provided by the basic attributes in Chapter 7 Controlling Licensing Behavior They should be used with care and questions are welcomed before the ir use These attributes are summarized in Table 8 2 Table 8 2 Advanced FLEXible API Attributes Attribute Description LM_A_BEHAVIOR_VER Sets FLEX m behavior to the given version LM_A_CHECKOUT_DATA Allows labeling of a given checkout request LM_A_CHECKOUTFILTER Defines a pointer to a checkout LM_A_CHECKOUTFILTER_EX filter func
21. Ic_new_job FLEXIm Reference Manual August 2004 125 FLEXible API Function Descriptions 6 4 16 Ic_log SYNTAX void lc_log job msg DESCRIPTION Logs a message in the debug log file if the license is served by Imgrd PARAMETERS LM_HANDLE job From Ic_new_job char msg The message to be logged The maximum length of msg is LM_LOG_MAX_LEN RETURN None ERROR RETURNS LM_NOSOCKET Communications failure to daemon LM_CANTWRITE Write error sending message to daemon 6 4 17 Ic_new_job 126 SYNTAX VENDORCODE code LM_HANDLE job LM_HANDLE NULL status lc_new_job prevjob lc_new_job_arg2 amp code amp job DESCRIPTION Ic_new_job initializes FLEX m and creates a license job Subsequent calls to Ic_new_job create new license jobs Each license job is independent Ic_new_job is used with licensed applications For license generators like Imcrypt and makekey use Ic_init instead All applications must link 1m_new o 1m_new ob3 on Windows into the application executable Failing to link 1m_new o into the executable will result in unresolved references to 1_n36_buf FLEXible API FLEXible API Function Descriptions Note The application must call Ic_new_job before calling any other FLEX m function including lc_set_attr and Ic_get_attr PARAMETERS LM_HANDLE prevjob Must be NULL on first call to Ic_new_job On subsequent calls use any ex
22. can be used to retrieve all the parameters that Is_checkout requires 13 2 11 Is_show_vendor_def int ls_show_vendor_def 0 If non zero the vendor daemon will send Your client can send a vendor defined checkout string to the daemon on each checkout request If 1s_show_vendor_def is non zero this data will appear in Ic_userlist calls and hence in Imstat output If you use this vendor defined checkout data and wish for your users to be able to view it with lmstat then set 1s _show_vendor_def to l 13 2 12 Is _user_init1 void ls_user_initl 0 To install an initialization routine that runs before normal vendor daemon initialization initialize 1s_user_init1 with a pointer to your routine and make sure an object file with this function is linked with your vendor daemon 13 2 13 Is_user_init2 void ls_user_init2 0 To install an initialization routine that runs after normal vendor daemon initialization initialize 1s_user_init2 with a pointer to your routine and make sure an object file with this function is linked with your vendor daemon 232 Vendor Daemon Vendor Variables 13 2 14 Is_user_init3 void ls_user_init3 0 To install an initialization routine that runs after the license file is read and after each lmreread initialize 1s_user_init3 with a pointer to your routine and make sure an object file with this function is linked with your vendor daemon 13 2 15 ls_vendor_msg char
23. 295 lc_auth_data 90 and demo licensing 199 lc_baddate 295 lc_check_key 160 and Ic_convert 162 lc_checkin 91 and lingering licenses 208 Ic_checkout 92 and LM_A_CHECKOUT_ FILTER 179 180 lc_checkout limits 274 lc_chk conf 296 Ic_ck_feats 296 Ic_cleanup 162 Ic_convert 162 LC_CONVERT_TO_DECIMAL 163 LC_CONVERT_TO_READABLE 163 lc_copy_hostid 296 and lc_free_hostid 164 lc_cryptO 296 lc_cryptstr 101 Ic_disalarm 296 Ic_disconn 296 Ic_display 296 Ic_err_info 107 Ic_errstring 109 and lc_perror 129 Ic_errtext 296 lc_expire_days 110 Ic_feat_list 111 Ic_feat_set 296 Ic_first_jobQ 112 Ic_free_hostidQ 164 and 1_new_hostid 158 Ic_free_job 113 lc_free_mem and Ic_convert 163 and Ic_cryptstr 105 Ic_get_attr 114 Ic_get_config 164 Ic_get_errno 166 Ic_get_feats 297 Ic_gethostid 297 Ic_getid_type 297 Ic_heartbeat 115 149 and LM_A_PERIODIC_COUNT 185 lc_hostid 118 lc_hostname 297 Ic_idle Q 123 Ic_init 124 and license generators 126 Ic_init_simple_composite 167 236 Ic_isadmin 297 Ic_log 126 Ic_new_job 126 and Ic_free_job 113 and multiple jobs 209 license job 126 Ic_next_conf 169 Ic_next_job 128 Ic_perror 129 and LM_A_USER_EXITCALL 148 Ic_remove 170 Ic_set_attr 130 and lingering licenses 208 limits 274 setting license file location 93 Ic_set_errno 297 Ic_shutdown 171 Ic_status 131 Ic_test_conf 172 308 FLEXIm
24. 4 M1 USB memory key FLEXible API Table 6 11 Hostid Types Continued FLEXible API Function Descriptions Operating System Microsoft Windows FLEX m Platform All Supported Hostid Types id_type HOSTID_DISK_ SERIAL_NUM Description Windows disk serial number HOSTID_ETHER Ethernet address 32 bit only 98 Me NT 2000 XP Server 2003 HOSTID_FLEXID6 FLEXID 6 Replaces FLEXID 7 e Mfg Rainbow Technologies SafeNet Inc e Device Parallel based iKey authentication token No USB support on NT HOSTID_FLEXID7 FLEXID 7 No longer available replaced by FLEXID 6 e Mfg Rainbow Technologies SafeNet Inc e Device Parallel based iKey authentication token HOSTID_FLEXID8 FLEXID 8 e Mfg Dallas Semiconductor Maxim Integrated Products Inc e Device 1 Wire parallel port adapter HOSTID_FLEXID9 FLEXID 9 e Mfg Aladdin Knowledge Systems Device HASP 4 M1 USB memory key except NT FLEXIm Reference Manual August 2004 121 FLEXible API Function Descriptions Table 6 11 Hostid Types Continued Operating FLEX m Supported Hostid Description System Platform Types id_type P Red Hat All HOSTID_ETHER Ethernet address Linux HOSTID_FLEXID9 FLEXID 9 Version 7 e Mfg Aladdin and greater Knowledge Systems 32 bit only Device HASP 4 M1 USB memory key SCO All HOSTID_ID_STRING String ID max
25. 73 4 LM_A_CHECK_BADDATE 00065 142 7 3 5 LM_A _CHECK_INTERVAL 0 0 0005 142 7 3 6 LM_A_CKOUT_INSTALL_LIC 143 7 3 7 LM_A_FLEXLOCK 0 0 0 0 0 ccc cece nee 143 7 3 8 LM_A_FLEXLOCK_INSTALL_ID 143 13 97 EMA ERSLIST eii iaa taa 144 7 3 10 LM_A_LICENSE DEFAULT 144 FLEXIm Reference Manual August 2004 7 3 11 LM_A _LICENSE_FMT_VER o oococcooocooooo 145 de Sek 2 LMA LINGER crs oa tl A et BO Se ie 145 7 3 13 LM_A_LONG_ERRMSG 0 000 e cee eee 146 7 3 14 LM_A_PERROR_MSGBOX Windows Only 147 7 3 15 LM_A _PROMPT_FOR_FILE Windows Only 147 7 3 16 LM_A_RETRY COUNT LM_A_RETRY_INTERVAL 147 7 3 17 LM_A_TCP_TIMEOUT co o cocccccccccccccoc o 147 7 3 18 LM_A_USER_EXITCALL LM_A_USER_EXITCALL_EX 148 7 3 19 LM_A _USER_RECONNECT LM_A_USER_RECONNECT_EX 149 7 3 20 LM_A_USER_RECONNECT_DONE LM_A_USER_RECONNECT_DONE_EX 151 7 3 21 LM_A_VD_GENERIC_INFO LM_A_VD_FEATURE_INFO 05 152 7 3 22 LM_A_VENDOR_ID_DECLARE 155 7 3 23 LM_A_VERSION LM_A_REVISION 155 7 3 24 LM_A_WINDOWS_MODULE_HANDLE Windows only 155 Chapter 8 Advanced FLEXible API Features 0 000005 157 8 1 Advanced FLEXible API Functions 0 00005 157 8 1 1 Tinew hostidO ina Bes tata ake he ie eo ti ss 158
26. 8 1 2 le borrow Tetum A SR ee as 159 B13 WeccheckKeKe yO sea ak te ie eee AN Se os 160 8 1 4 lc_cleanupO Windows only 0 02 eee eee 162 SL ICSCONVE sx deus ease tek Sad boas ahh orale da das 162 8 1 6 lc_free_hostidO corseira ccc cece ene 164 SEF O sn eid Ae ei A Eee Bea os 164 81 8 Ico get ermo ey aed ccs as 166 8 1 9 Ic_init_simple_composite 0 sanean nrnna 167 SAO AC DEREC ra ale ted ae el ee Re 169 SLA deremo tii ae bah ae wad ate le ed 170 8 1 12 Ic_shutdown es dessns 0 00 0 171 81 13 Te es tZEOM ta e at ab tals 172 8 2 Advanced FLEXible API Attributes o ooooooooo 174 8 2 1 LM_A BEHAVIOR_VER 00 0000 cece eens 175 8 2 2 LM_A CHECKOUT_DATA 0 00055 176 8 2 3 LM_A_CHECKOUTFILTER LM_A_CHECKOUTFILTER_EX 179 8 2 4 LM_A CHECKOUTFILTERLAST_EX 180 8 2 5 LM_A_CRYPT_CASE_ SENSITIVE 182 FLEXIm Reference Manual August 2004 vii 8 2 6 LM_A _DIAGS ENABLED 04 182 8 27 EM A DISABLE ENV das 182 8 2 8 LM_A DISPLAY _OVERRIDE 2 183 8 2 9 LM_A _HOST_OVERRIDE 0004 184 8 2 10 LM_A _LICENSE_CASE_SENSITIVE 184 8 2 11 LM_A_MT_HEARTBEAT UNIX Only 184 8 2 12 LM_A PERIODIC_CALL 04 185 8 2 13 LM_A_PERIODIC_COUNT 005 185 8 2 14 LM_A PLATFORM_OVERRIDE 185 8
27. 8 1 6 164 e Section 6 4 4 Ic_cryptstr because Ic_convert has a similar interface to Ic_cryptstr e Section 7 3 11 LM_A_LICENSE_FMT_VER Ic_free_hostid SYNTAX void lc_free_hostid job hostid DESCRIPTION Ic_free_hostid frees the memory associated with a hostid which has been allocated with _new_hostid or lc_copy_hostid If passed a hostid list Ic_free_hostid frees the whole list Ic_free_job removes any timers associated with job PARAMETERS LM_HANDLE job From Ic_new_job HOSTID hostid From _new_hostid RETURN None ERROR RETURNS LM_BADPARAM No such job SEE ALSO e Section 8 1 1 1_new_hostid Ic_get_config SYNTAX conf lc_get_config job feature DESCRIPTION Gets the license file data for a given feature FLEX m allows multiple valid FEATURE and INCREMENT lines of the same feature name in a license file lc_get_config will return the first CONFIG struct and Ic_next_conf retrieves the next Ic_next_conf can also find the first lc_get_config does Advanced FLEXible API Features Advanced FLEXible API Functions not authenticate feature lines That is a user can type in a FEATURE line with an invalid signature and Ic_get_config will still return it lc_get_config and Ic_next_conf are usually needed only with LM_A_VD_GENERIC_INFO or LM_A VD_FEATURE_INFO To get authenticated information from a FEATURE line you must first ch
28. If reconnection fails then the reconnect will be re attempted LM_A_RETRY_COUNT times at intervals of LM_A_RETRY_INTERVAL If the application wants manual control over this activity enable manual heartbeats by setting LM_A_RETRY_INTERVAL to 1 and LM_A_CHECK_INTERVAL to 1 The minimum value for LM_A_RETRY_INTERVAL is 30 seconds If LM_A_RETRY_COUNT is set to 1 the application will attempt retrying forever for applications desiring a more lenient policy this is recommended SEE ALSO e Section 6 4 12 Ic_heartbeat e Section 7 3 5 LM_A_CHECK_INTERVAL e Section 7 3 18 LM_A_USER_EXITCALL LM_A_USER_EXITCALL_EX 7 3 17 LM_A_TCP_TIMEOUT Type int Default 7200 seconds 2 hours FLEXIm Reference Manual August 2004 147 FLEXible API Attributes set by Ic_set_attr Maximum 15300 seconds 4 hours 15 minutes If a TCP client node crashes or the client node is disconnected from the network the license will be automatically checked back in LM_A_TCP_TIMEOUT seconds later 0 means no TCP timeout SEE ALso e Section 6 4 12 Ic_heartbeat 7 3 18 LM_A USER EXITCALL Note 148 LM_A USER EXITCALL_EX Type Pointer to a function returning int Return value unused Default No user exit handler licensed application exits DESCRIPTION The function pointer LM_A_USER_EXITCALL or the extended version LM_A_USER_EXITCALL_EX is set to point to the callback routine that is to receive control
29. Ip_checkout when vendor name is not demo but encryption seeds are default encryption seeds Feature removed during lmreread or wrong SERVER line hostid Checkout failure due to two possible causes 1 The feature is removed during Imreread but the client is reading an old copy of the license file which still has removed feature 2 The hostid on the SERVER line is for a different host so all features in this license file were removed This feature is available ina different license pool This is a possible response to LM_A_VD_FEATURE_INFO request indicating that this INCREMENT line can be ignored as it has been pooled with another line Attempt to generate license with incompatible attributes Occurs with verfmt arguments to lmcrypt or makekey or for lminstall overfmt Also set by Ic_cryptstr and Ic_chk_conf Network connect to THIS_HOST failed Returned by checkout When this_host is used as a host name Replace this_host with a real host name to resolve this error 290 FLEXIm Status Return Values 96 LM_HOSTDOWN 97 LM_VI 98 ENDOR_DOWN LM_CANT_DECIMAL 99 LM_BADDECF ILE 100 LM_RI EMOVE_LINGER 101 LM_RI 102 ESVFOROTHERS LM_BORROW_ERROR Error Number Table Server node is down or not responding Returned by checkout indicates the whole license server system is not up not just the
30. Program Files flexlm i86_n3 lmgrd is the location of the Imgrd executable Double quotes are required around the name since there is an embedded space in one of the folder names C mylicenses sample lic is the full path name for the license file C mylogfiles sample dl is the full path name for the debug log file Myvendor License Manager is the service name Double quotes are required since the service name is composed of multiple words e To remove the service named Myvendor License Manager installed in the previous example installs r n Myvendor License Manager e To install Imgrd as a service and to configure the Imgrd startup parameter x lmremove installs e C Program Files flexlm i86_n3 lmgrd c C mylicenses sample lic 1 C mylogfiles sample dl n Myvendor License Manager k x Ilmremove Now each time Imgrd starts up it will be invoked with the x 1mremove parameter FLEXIm Reference Manual August 2004 263 Installing Imgrd as a Service Using installs 264 Windows Platform Specific Notes Industry Standard Licensing APIs FLEXI m offers the most widely used licensing API available the FLEX m API which is used by over 1500 software vendors worldwide However there has been much effort expended in the search for a standard licensing API FLEX m offers the vendor the choice of six standard APIs FLEX m Trivial API FLEX m Simple API FLEX m FLEXible
31. SYNTAX status l1lc_checkout job feature version num_lic flag code dup_group DESCRIPTION Checks out one or more license s of the specified feature If the process that calls lc_checkout exits in any manner then the checked out license will be returned for re use by another user For TCP clients the resulting checkin is immediate FLEXible API FLEXible API Function Descriptions Place the call to lc_checkout in an executable that is active whenever the user is using the feature If flag is specified as LM_CO_WAIT then the process will wait until the number of licenses requested for this feature are available The license file must specify a version that is greater than or equal to the version in the call to Ic_checkout If the license file is counted that is if the number of users specified on the FEATURE line is non zero Ic_checkout will request the license from a license server If the number of users on the FEATURE line is uncounted it will grant permission based on the contents of the license file only hostid version expiration date etc e Before a call to the checkout function it is recommended that the application first indicate the expected license file location with Ic_set_attr job LM_A_LICENSE_DEFAULT LM_A_VAL_TYPE license file list The license_file_list is a location in your installation hierarchy which indicates the expected license file location This is a di
32. The breakdown of the SERVER and VENDOR lines is illustrated here SERVER pat 17003456 2837 Host Name Port Keyword Hostid VENDOR demo Vendor Daemon Name Keyword Host name can be changed by the end user If host name is this_host clients running on the same node as the server work fine Clients on other nodes fail unless the host name is changed or the clients use host or port host if a port number is specified on the SERVER line to find the server FLEXIm Reference Manual August 2004 27 Types of License Files 2 3 4 2 3 5 28 Since a vendor_daemon_ pathis not specified in the VENDOR line lmgrd uses the current directory or the PATH environment variable in its environment to find the vendor daemon binary Nothing else can be changed on these two lines Everything else is authenticated by the signature Floating with Three Server Redundancy ERVER pat 17003456 2837 ERVER lee 17004355 2837 ERVER terry 17007ea8 2837 ENDOR demo EA URE f1 demo 1 0 1 jan 2005 10 SIGN 1AEEFC8F9003 Hj uU EA URE 2 demo 1 0 1 jan 2005 10 SIGN 0A7E8C4F561F A three server redundant configuration is specified This is a a set of three server nodes all running the same operating system any two of which must be running for FLEX m to function Three SERVER lines and one VENDOR line required All three servers communication via the same TCP IP port Two features are licensed
33. You pass via the st r parameter a license certificate template which is a complete valid unsigned SIGN 0 license certificate containing one or more FEATURE INCREMENT PACKAGE or UPGRADE lines A signed license certificate is returned via return_str For example consider the following license certificate template as input via str FEATURE f1 demo 1 5 0l jan 2005 uncounted HOSTID 08002b32b161 SIGN 0 Ic_cryptstr calculates the signature and returns the complete valid license certificate in return_str FEATURE f1 demo 1 5 0l1 jan 2005 uncounted HOSTID 08002b32b161 SIGN 2C817A5100D8 FLEXIm Reference Manual August 2004 101 FLEXible API Function Descriptions 102 If flag has LM_CRYPT_ONLY set then the function returns the signature for the first FEATURE INCREMENT PACKAGE or UPGRADE line in the certificate If LM_CRYPT_ONLY is cleared then the entire certificate is signed and returned as a string If flag has LM_CRYPT_FORCE set then the signature is recomputed for every line even if the signature is defined Comment lines are retained in the return_str output If you want to specify a start date then add the following keyword to the license line template using the following syntax START dd mmm y y y y Example START 1 Jan 2005 The output is compatible with the LM_A_ LICENSE_FMT_VER setting which defaults to the current FLEX m version The complete source for the Imc
34. e Section 7 3 5 LM_A_CHECK_INTERVAL e Section 6 4 12 Ic_heartbeat 8 2 13 LM_A_PERIODIC_COUNT Type int Default 0 no PERIODIC_CALL This is the count of how many times Ic_heartbeat must be called before the function specified by LM_A_PERIODIC_CALL is called Ic_heartbeat is called directly or automatically depending on the value of LM_A_CHECK_INTERVAL SEE ALSO e Section 7 3 5 LM_A_CHECK_INTERVAL e Section 6 4 12 Ic_heartbeat 8 2 14 LM_A_PLATFORM_OVERRIDE Type char Default No override of the FLEX m platform name This string if specified overrides the current platform name The name can be either a FLEX m platform name or a vendor defined name This attribute is used in conjunction with the PLATFORMS keyword on FEATURE INCREMENT lines The FLEX m Release Notes contain the currently supported platforms and their associated FLEX m platform names SEE ALSO e Section 3 5 16 PLATFORMS e FLEXIm Release Notes located in the machina directory of the FLEX m SDK FLEXIm Reference Manual August 2004 185 Advanced FLEXible API Attributes 8 2 15 LM_A_RETRY_CHECKOUT Type int Default True When True checkouts that fail due to communications errors are automatically retried once Sometimes this second attempt will succeed on networks with poor communications but this makes failure take twice as long This is default behavior in all of the FLEX m APIs 8 2 16 LM_A_USER_O
35. happ RegCloseKey hcpl 260 Windows Platform Specific Notes Installing Imgrd as a Service Using installs 18 9 Installing Imgrd as a Service Using installs To install lmgrd as a service use the facility provided in LMTOOLS or use the installs exe utility provided by FLEX m in the plat form directory installs exe can be used as a command line utility to manually install the service or can be embedded in your end user installation procedure to automatically install the service on behalf of the user at installation time Usage is installs c 8 I n license_file_path Imgrd_location log_file_path service_name Y k lmgrd parameters To remove Imgrd as a service installs r n service_name where imgrd_location license_file_path k log_file_path service_name Location of Imgrd exe on your system Path names with embedded spaces need to be enclosed in double quotes Location of the license file Path names with embedded spaces need to be enclosed in double quotes Location for the debug log file Path names with embedded spaces need to be enclosed in double quotes The service name If not specified FLEX1m License Manager is used by default Service names with embedded spaces need to be enclosed in double quotes FLEXIm Reference Manual August 2004 261 Installing Imgrd as a Service Using installs k Imgrd parameters Used to pass additional command line argum
36. lpChallenge S_ULONG TotUnitsGranted LS_STATUS_CODE LSRequest LS_STR Request license LicenseSystem LS_STR PublisherName LS_STR ProductName LS_STR Version LS_ULONG TotUnitsReserved LS_STR LogComment LS_CHALLENGE Challenge J iS _ULONG TotUnitsGranted LS HANDLE Handle The challenge in your first LSRequest call must be of type LS_CHALLENGE_FLEXLM which is a FLEX m vendor specific challenge mechanism Challenge should be setup as in the following code example before calling LSRequest LS_CHALLENGE_FLEXLM Challenge LM_CODE vendor_code ENCRYPTION_SEED1 ENCRYPTION_SEED2 VENDOR_KEY1 VENDOR_KEY2 VENDOR_KEY3 VENDOR_KEY4 VENDOR_KEY5 Challenge gt Protocol LS_FLEXLM_PROTOCOL strcpy Challenge gt ChallengeData VendorName VENDOR_NAME Challenge gt ChallengeData VendorCode vendor_code Challenge gt Size sizeof Challenge LSRequest sacking ES CHALLENGE Challenge cs For more details on the LSAPI interface see the License Service Application Programming Interface API Specification v1 1 or contact Microsoft via e mail at Isapi O microsoft com or Dave Berry Microsoft Developer Relations 1 Microsoft Way 4 2 Redmond WA 98052 6399 Industry Standard Licensing APIs LSAPI General Calls Remember you cannot mix LSAPI and native FLEX m calls in a single application The licens
37. mapfile Reads mapfile mapfile Forces randomized names to be the same across invocations Default mapfile name is lmstrip map FLEXIm Reference Manual August 2004 213 Security and FLEXIm 214 mw mapfile mrw mapfile o string_file filename P Writes mapfile map f 1 le This file contains a lookup table of obfuscated symbol names that can be used in later invocations Default mapfile name is lImstrip map Reads and updates mapfile mapf ile Default mapfile name is lmstrip map A file containing one or more vendor specified symbol names to obfuscate in filename One symbol name per line of the form e symbol Adds the symbol to the list of vendor specified symbols to be obfuscated e symbol Removes the symbol as an obfuscation candidate symbol can be either a FLEX m symbol name or a vendor specified symbol name Name of the file to process Displays the list of non FLEX m symbol names in filename Used in conjunction with mr mapf ile symbols that have already been obfuscated are suppressed from the list Displays a list of all FLEX m internal and external symbol names to be obfuscated ADDING SECURITY TO UNIX APPLICATION BINARIES When the UNIX strip command processes a dynamically linked binary it leaves external symbol names intact in case they are referenced from a shared library Using 1mstrip on a dynamically linked binary adds more security because it obfuscates all FLEX m symbol nam
38. 00 1 jan 0000 Number of Licenses Number of licenses for this feature a value greater than 0 denotes a counted license Use uncounted or 0 for unlimited use of node locked licenses BORROW BORROW n Optional field Enables license borrowing for a particular FEATURE INCREMENT line see the FLEXIm Programmers Guide for more information about license borrowing n is the maximum number of hours that the license can be borrowed for The default maximum borrow period is 168 hours or one week BORROW licenses are susceptible to extra uses should a user stop and restart the licenses server while licenses are borrowed A lower value of n minimizes the affects of the possible use of extra licenses A software vendor may choose to issue BORROW licenses only to their trusted customers The maximum borrow period is limited by the maximum value of a 32 bit integer 2 billion hours DUP_GROUP DUP_GROUP NONE SITE UHDV Optional field If DUP_GROUP is specified in the license this parameter overrides the dup_group parameter in the call to lc_checkout If not specified in the license the dup_group parameter from lc_checkout will be used The syntax is DUP_GROUP NONE SITE UHDV U DUP_USER H DUP_HOST D DUP_DISPLAY V DUP_VENDOR_DEE The License File Syntax 3 5 8 3 5 9 FEATURE INCREMENT Lines Any combination of UHDV is allowed and the DUP_MASK is the OR
39. 2 LM_DUP_NONE Check out 5 more licenses for fl label them second checkout lc_set_attr lm_job LM_A CHECKOUT_DATA second checkout lc_checkout lm_job f1 1 0 5 LM_DUP_NONE Check in 2 licenses for f1 labeled first checkout lc_set_attr lm_job LM_A_CHECKOUT_DATA first checkout lc_checkin lm_job f1 0 Check in 5 licenses for fl labeled second checkout lc_set_attr lm_job LM_A_CHECKOUT_DATA second checkout lc_checkin lm_job f1 0 This makes it possible to have different sets of licenses for a given feature without having to create a separate license job Each set is labeled with a different checkout data string and is tracked separately by the license server Subsequent check in requests then can qualify the feature with the checkout data string by setting it with the LM_A_CHECKOUT_DATA attribute before calling Ic_checkin Each checkout or checkin request uses the value of the checkout data string from the last call to lc_set_attr CUSTOM DUPLICATE GROUPING Duplicate grouping based on USER HOST or DISPLAY may not represent the duplicate grouping criteria you need The checkout data string can be used to group duplicates via a custom vendor criteria in addition to the USER HOST DISPLAY duplicate grouping criteria Set the checkout data string using the LM_A_ CHECKOUT_DATA attribute and then in the subsequent call to lc_checkout set the LM_DUP_VENDOR bit in
40. A policy can be modified by ORing it with a list of optional modifiers see Section 7 2 Trivial and Simple API Policy Modifiers The following license policies are available e LM_RESTRICTIVE e LM_QUEUE e LM_FAILSAFE e LM_LENIENT 7 1 1 LM_RESTRICTIVE With this policy any failure in the license checkout or server will be reported to the calling application as an error The application decides what action to take with this error it is not necessary that the application fail to run For example the application may report the error and continue running it may exit or it may run in a limited mode FLEXIm Reference Manual August 2004 137 Trivial and Simple API Policy Modifiers 7 1 2 7 2 7 2 1 138 LM_QUEUE This policy is the same as LM_RESTRICTIVE except that the checkout call will wait for a license if the licenses are all currently in use To the end user the application will appear to hang until the license is available LM_FAILSAFE With this policy the application will attempt a checkout but no checkout failures of any kind will be reported to the calling application This policy provides optional licensing to the user If the user wants to use licensing he can in which case the checkout will succeed If the user doesn t want to use licensing or if licensing is for some reason broken applications will always continue to run In the case where all licenses are currently in use
41. DLL Macrovision also provides a library compiled with MD multithreaded using the C Runtime Library as a DLL called Imgr_md lib e Linking dynamically with the FLEX m DLL less secure The DLL version is called Imgr9a d11 with its associated import library lmgr9a lib The lmgr9a d11 library is built using the multithreaded statically linked C Runtime Library Use the FLEXible API for enhanced DLL security If it is necessary to use the FLEX m DLL please send email to support macrovision com to get suggested enhancements to improve the security of your application If your application is a DLL and the FLEX m library is linked into this DLL then you need to set one special attribute to allow the Windows context to be properly set See Section 7 3 24 LM_A_WINDOWS_MODULE_HANDLE Windows only Windows Terminal Server Support FLEX m detects when a node locked uncounted license is running under Windows Terminal Server To run on Terminal Server client machines the license is node locked to the Terminal Server machine and the TS_OK keyword is added to the license For example FEATURE f1 xyzd 1 00 1 Jjan 2005 uncounted HOSTID ts_hostid Y TS_OK SIGN sign Without the TS_OK keyword on a feature line a user running on a Terminal Server client machine will be denied use of a license In each of the following cases application A is installed on a Terminal Server machine with its license locked to Terminal Server m
42. Description Ip_errstring Returns a string describing the most recent error Ip_perror Presents current error message to user Ip_pwarn Presents current warning message to user Ip_warning Returns a string describing the most recent warning Simple API Function Descriptions Ip_checkin SYNTAX void lp_checkin lp_handle DESCRIPTION Releases a license and frees memory associated with the corresponding checkout Ip_checkin should be called even if the checkout fails in order to free associated memory and resources Simple API 5 2 2 Simple API Function Descriptions PARAMETER LP_HANDLE 1lp_handle The handle from the lp_checkout call Ip_checkout SYNTAX include lmpolicy h LP_HANDLE lp_handle status lp_checkout LPCODE policy feature version num_lic license file list amp lp_handle DESCRIPTION Acquires a license for a feature PARAMETERS LPCODE_HANDLE LPCODE From the impolicy h header file Use the literal LPCODE int policy See Section 7 1 Trivial and Simple API License Policies Example LM_RESTRICTIVE char feature The desired feature name to check out FLEXIm Reference Manual August 2004 75 Simple API Function Descriptions char version int num_lic char license file list pointer to LP_HANDLE lp handle 76 Simple API The version of the feature to check out This is a stri
43. GATE deo Set attr A wales whic iow wh ete wea 114 64 12 Iexheartheat Qc sinc sine ce iia Ste ae eae is 115 64 13 le hostid caia all es havea ae he wes ae ee ee 118 A A Bee ed ENE Re HES 123 ALSO SADO it Oriel solos hens eed hd Ble ete AE 124 64 16 llo oss ie eet ea el kia be asia tala 126 64 17 Ic mew _jobO cnet Yk wee ey oda dase 126 6 4 18 Ic_next_jobQ 0 cece eens 128 GALO le perror 02 set oan ews tow oe doula dau esas 129 64 20 We Set attr ety vee x dar tien aa Rosenstein he 130 6 4 21 A RS O AA MoS tht ites See toe Ree 131 64 22 Te USCHUSTO ts na ven eats Wem E Wek ow eae AEA as 133 64 23 HCV SENG iii rd ed Pesce ted a nega eas 134 Controlling Licensing Behavior 0 000005 137 7 1 Trivial and Simple API License Policies 137 TAA EM RESTRICTIV Ee cocoa 137 24 22 A EM QUEUE ute eaten lia 138 AALS JEM FAILSAFE AA 138 TRA EM EENTEND a at id 138 7 2 Trivial and Simple API Policy Modifiers 138 7 2 1 LM_MANUAL_HEARTBEAT 0055 138 7 2 2 LM_RETRY_RESTRICTIVE oo oo ooococoooooo 139 7 2 3 LM_CHECK_BADDATE 00 0000 ues 139 124 IUM BLEXLOCK lt 0 aye sce it a Mee GE 139 7 3 FLEXible API Attributes set by lc_set_attr 139 7 3 1 LM_A_APP_DISABLE_CACHE_READ 140 73 22 LM_A_BORROW_EXPIRE 00 00 e ee euee 141 7 3 3 LM_A_BORROW_STAT 0 0 0000 cece eee eee 141
44. Ic_checkout e Section 8 2 3 LM_A_CHECKOUTFILTER LM_A_CHECKOUTFILTER_EX e Section 8 2 4 LM_A_CHECKOUTFILTERLAST_EX Ic_checkin SYNTAX void lc_checkin job feature keep_conn FLEXIm Reference Manual August 2004 91 FLEXible API Function Descriptions 6 4 3 92 DESCRIPTION Checks in the licenses of the specified feature For TCP clients the daemon will detect the fact that the client exited and return any licenses that were checked out back to the available pool For TCP this function is called if the application has need of a feature for a period of time then no longer needs it The second parameter is used for TCP clients to tell FLEX m to keep the connection open to the server for cases where another feature will be needed shortly after this one is released If the communications protocol is TCP there is no appreciable time delay incurred in returning the license if the program exits rather than returning the license via Ic_checkin For reporting purposes in the report log file it is preferable to check in a license with Ic_checkin rather than simply exiting because these two types of events are recorded differently in the report log file PARAMETERS LM_HANDLE job From Ic_new_job char feature The feature name to be checked in or LM_CI_ALL_FEATURES int keep_conn If non zero means Keep connection to server If 0 drops TCP connection RETURN None Ic_checkout
45. If there is an error lc_userlist returns NULL and sets the job error status Ic_userlist returns only information about users the server knows about therefore it will not return any information about users of node locked uncounted or DEMO licenses unless the server s license file includes the FLEXIm Reference Manual August 2004 133 FLEXible API Function Descriptions node locked licenses and the client is not reading the license file via Ghost port host or USE_SERVER Queued users and licenses shared due to duplicate grouping are also not returned by Ic_userlist Reserved licenses are indicated by the Im_isres macro defined in lmclient h In this case the name contains the entity that the reservation is for ERROR RETURNS LM_BADCOMM Communications error with license server LM_CANTMALLOC The call to malloc failed LM_FUNCNOTAVAIL Vendor keys do not support this function LM_NOFEATURE Specified feature cannot be found SEE ALSO e machind Ilmclient h for LM_USERS structure definition 6 4 23 Ic_vsend 134 SYNTAX rcv_str lc_vsend job send_str DESCRIPTION Sends a message to the vendor daemon and returns a result string If the client is not already connected to a server this function will connect to the first server in the first license file in its list The string can be up to 140 bytes You must set up a processing routine in your vendor daemon to receive the message from Ic_vsend an
46. Imgrd process The desired vendor daemon is down Returned by checkout indicates lmgrd is running but not the vendor daemon The FEATURE line can t be converted to decimal format Returned by Ic_cryptstr or Imcrypt makekey Iminstall See Section 3 8 Decimal Format Licenses for information on what can t be converted to decimal format The decimal format license is typed incorrectly The internal checksum on the decimal line has indicated the line has been typed incorrectly Cannot remove a lingering license Returned to Imremove command User has already exited but license is lingering Imremove doesn t remove the linger time All licenses are reserved for others Checkout return value when a checkout will never succeed because the end user options file has all licenses reserved for others A FLEXid borrow error occurred FLEXIm Reference Manual August 2004 291 Error Number Table 103 LM_TSOK_ERR 104 LM_BORROW_TOOLONG 106 LM_SERVER_MAXED_OUT 110 LM_NODONGLI S112 E LM_NODONGLEDRIVER 113 LM_FL 114 EXLOCK2CKOUT LM_SIGN_REO 115 LM_PUBKEY_ERROR Terminal Server remote client not allowed The feature line does not contain TS_OK to allow Terminal Server client usage Cannot borrow that long The user has specified a borrow period longer than the license allows
47. In addition once a user checks out a license for one component licenses for the other package components are reserved by the license server for that user A set of package components remain reserved for the given user until all licenses for the set are checked back in The SUITE_DUP_GROUP FEATURE line keyword must be specified in conjunction with OPTIONS SUITE_RESERVED PACKAGE line keyword in order to get the reserved package component behavior PACKAGE office demo 1 0 COMPONENTS write paint draw OPTIONS SUITE_RESERVED SIGN 00504091605D FEATURE office demo 1 0 permanent 2 SUITE_DUP_GROUP U DUP_GROUP NONE SIGN DB5CC00101A7 The License File Syntax PACKAGE Lines This license file defines a package suite named of fice with three components write paint and draw Note that the suite duplicate grouping criterion SUITE_DUP_GROUP U is defined in this example to the user level the feature duplicate grouping criterion DUP_GROUP NONE is the default and is supplied in this example for clarity At most two distinct users can be granted licenses at any one time and once one component is checked out the others in the package are reserved for that user This concept is illustrated in the following table with two users License Checkout User Attempt Requested Result Explanation Feature 1 ul write granted User ul checks out one component thereby reserving one package license 2 u2 paint grant
48. LM_A_RETRY_INTERVAL e Section 8 2 17 LM_A_VENDOR_CALLBACK_DATA 7 3 19 LM_A_USER_RECONNECT LM_A USER RECONNECT EX Type Pointer to a function returning int Return value unused Default No user reconnection handler DESCRIPTION The function pointer LM_A_USER_RECONNECT or the extended version LM_A_USER_RECONNECT_EX is set to point to a reconnection callback routine This routine is called each time just before a reconnection is attempted either by the automatic heartbeat mechanism or as a result of the application program calling Ic_heartbeat The LM_A_USER_RECONNECT routine is called as follows reconnect feature pass total_attempts interval or with LM_A_USER_RECONNECT_EX reconnectEx job feature pass total_attempts interval vendor_data FLEXIm Reference Manual August 2004 149 FLEXible API Attributes set by Ic_set_attr Note LM_A_USER_RECONNECT_EX provides a way to pass vendor defined data to this callback function Behavior is undefined if both LM_A_USER_RECONNECT_EX and LM_A_USER_RECONNECT are set CALLBACK PARAMETERS LM_HANDLE job LM_A_USER_RECONNECT_EX only A pointer to the current license job char feature Feature name int pass Current attempt number int total_attempts Maximum number of passes that will be attempted int interval Time in seconds between reconnection attempts void user_data LM_A_USER_RECONNECT_EX only A pointer to
49. Overview 2 2 Hostids for FLEXIm Supported Machines Any amount of white space can separate the components of license file lines data can be entered via any plain text editor Vendors can therefore distribute license data via fax or telephone 8 bit Latin based characters are fully supported in license files options files log files and client environments Hostids for FLEX m Supported Machines A hostid is a means used to uniquely identify a specific machine There are two different contexts in which a hostid is used A FLEX m license The license is bound to one or more hostids They are used to define which end user machines are licensed to run your product A FLEX m license server A hostid used to define which machine is authorized to run a license server that serves licenses to your FLEX m enabled product Each platform supports one or more methods of determining its hostid You need to determine which hostid types you accept for each platform you support The FLEX m utility imhost id prints the default hostid that FLEX m expects to use on any given platform FLEX m supports platform specific as well as vendor defined hostids In addition there are a number of special hostid types which apply to all platforms These special hostid types can be used on either a SERVER line or a FEATURE line wherever a hostid is required The appendix entitled Hostids for FLEX m Supported Machines in the FLEXIm End Users Guide
50. Technology but the performance is not equivalent to two physical processors System calls such as GetSystemInfo on these machines return the number of logical processors rather than the number of physical processors present in the system FLEXIm Reference Manual August 2004 195 Advanced License File Features 196 In order to accurately calculate the number of physical CPUs and thus determine an appropriate setting for the LM_A_ CAPACITY attribute use code provided by Intel located at http cedar intel com cgi bin ids dll content content sp cntKey Generic Editorial xeon cpu counter zcntType IDS EDITORIAL Advanced FLEXible API Features License Models 9 1 Demo Licensing There are many popular methods of handling demo licensing this section discusses the most popular However many companies have unique needs which may not be covered in this section Call your FLEX m salesperson for a description of the additional types of licensing models that FLEX m supports 9 1 1 Limited Time Uncounted Demos This is the most popular method Advantages include e No special coding is required in the application e No license server is required e License installation is easy e License files are easy to distribute since no end user information is required The license file should look like E EATURE fl corp 1 0 1 jan 2005 uncounted HOSTID DEMO SIGN ABOCC0C16807 This indicates the expi
51. a license pool for feature 1 The concurrent usage limit is 3 1 2 e The first INCREMENT line could be a FEATURE line and the behavior would be the same Now in contrast this next example shows separate pooling SERVER speedy 08002b32b161 VENDOR demo INCREMENT f1 demo 2 0 permanent 1 HOSTID 80029a3d SIGN 7B9F02AC0645 INCREMENT f1 demo 2 0 permanent 2 HOSTID 778da450 SIGN 6BAFD2BC1C3D FLEXIm Reference Manual August 2004 39 FEATURE INCREMENT Lines 40 e One license is available on hostid 80029a3d Two licenses are available on 778da450 e The server tracks these licenses independently in separate pools because the HOSTID fields are different e Since a license pool is not formed this independent tracking only works with INCREMENT not FEATURE because the server only recognizes the first FEATURE line for a given feature name Subsequent ones are ignored A single checkout request can not span multiple license pools That is if a checkout is requesting more licenses than are available in a single license pool the request is denied Consider the following example SERVER speedy 08002b32b161 VENDOR demo INCREMENT f1 demo 1 0 permanent 3 SIGN 2B8F621C172C INCREMENT f1 demo 2 0 permanent 4 SIGN 2B9F124C142C These lines form two separate license pools one with 3 licenses for v1 0 and one with 4 licenses for v2 0
52. aborts the operation returns 0 then it should set the error code via lc_set_errno 1m_job errno appropriately To obtain the parameters of the current checkin call use the ls_get_attr call described in Section 13 2 10 Is_outfilter Is_min_Imremove int ls_min_lmremove 120 Minimum amount of time seconds that a The imremove utility could be used to bypass the license count for a feature if an end user were to run Imremove on each user as soon as he had checked out a license 1s_min_lmremove makes the 1mremove utility ineffective for a certain period of time after a user connects to the daemon 120 seconds by default 13 2 9 Is minimum_user timeout int ls_minimum_user_timeout 900 Minimum user inactivity timeout seconds This is the minimum value in seconds that an end user can set the feature s TIMEOUT value An attempt to set a timeout less than ls_minimum timeout will result in the minimum value being set If 1s_minimum_user_timeout is set to 0 then the user TIMEOUT option is disabled 13 2 10 Is_outfilter Note 230 int ls_outfilter 0 Please contact Technical Support before using 1s_out filter Callbacks in this area are rarely needed and we re happy to provide assistance when they are Vendor Daemon Vendor Variables To install a vendor defined checkout filtering routine initialize 1s_outfilter with a pointer to your routine The checkout filter is called wit
53. at runtime rather than appearing as a literal string in the binary for a hacker to find and change EXAMPLE The following code is an example of a vendor defined callback function This example returns a string of three lock names TOM DICK and HARRY char MyCallBackFunction Return a string constructed dynamically at runtime For the purposes of this example a static string is returned Af return TOM DICK HARRY This callback is registered via the 1s_user_lock identifier char ls_user_lock MyCallBackFunction The callback function can be included directly into machind lsvendor cor can be linked in from another object file during the vendor daemon build process USAGE GUIDELINES FOR VENDOR DAEMON SYNCHRONIZATION e Windows Platforms If all vendor daemons involved in the synchronization are v8 2 or later use this mechanism for all daemons in the group 194 Advanced FLEXible API Features 8 4 8 4 1 Advanced License File Features If one or more vendor daemons involved in the synchronization are pre v8 2 see Section 8 3 10 Is_user_lockfile e UNIX Platforms This mechanism is not applicable see Section 8 3 10 ls user_lockfile Advanced License File Features CAPACITY CAPACITY Optional keyword The most common purpose of the CAPACITY keyword is to provide capacity based licensing Capacity could be based on any measure of a machine s resources This technique ef
54. automatically by FLEX m via a separate dedicated application thread See Section 12 1 Automatic Heartbeats for more details on automatic heartbeat messages This function provides manual control of heartbeat messages thereby overriding the automatic mechanism To use It_heartbeat HEARTBEAT you must first turn off the automatic mechanism by setting the LM_MANUAL_HEARTBEAT policy modifier in the It_heartbeat HEARTBEAT call If the license server goes down and later comes back up It_heartbeat HEARTBEAT automatically reconnects and checks the license out Each call to It_heartbeat HEARTBEAT makes one attempt to reconnect On failure it returns the cumulative number of failed attempts to reconnect to the license server in which case applications should at a minimum notify the user of the failure This provides a way for applications to monitor the number of reconnects and take appropriate action such as exiting when a predetermined limit is reached In addition applications may want to exit if reconnections succeed more than three or four times in a relatively short period e g ten minutes which may indicate a user restarting the license server in an attempt to acquire extra licenses FLEXIm Reference Manual August 2004 69 Trivial API Descriptions 4 2 5 4 2 6 70 Do not call It_checkout CHECKOUT on failure from It_heartbeat HEARTBEAT this is not necessary and will cause problems if attem
55. available on UNIX and Windows FLEX m features include e Operation in a heterogeneous network of supported computer systems e Transparent reconnection of applications when their license server process becomes unavailable including conditions of license server node failure FLEXIm Reference Manual August 2004 xiii Other Product Documentation xiv e Simple configuration by using a single license file per network e Configuration controls for system administrators e Administration tools for system administrators e Independent features from one or multiple vendors with independent vendor security codes e A wide variety of license policies and license styles including Floating licenses Node locked licenses Named user licenses Demo licenses Counted and uncounted licenses Optional license expiration dates Several vendor definable fields for each application feature Other Product Documentation The FLEXIm Programmers Guide provides an introduction to FLEXIm instructions for evaluating FLEX m on UNIX and Windows systems and guidelines for integrating FLEX m into your application The FLEXIm Java Programmers Guide contains guidelines for using FLEX m Java and the FLEX m Java API reference The FLEXIm End Users Guide contains information relevant to users of products that utilize FLEX m as their license management system including descriptions of the license administration tools which are bundled with FLEXIm It
56. but allow the end user to determine which hosts If n is specified then the number of hosts which can be INCLUDEd is limited to n Otherwise the limit is the num_lic field If an INCREMENT appears where some licenses are HOST_BASED and some are not the vendor daemon tracks these in separate license pools FLEXIm Reference Manual August 2004 43 FEATURE INCREMENT Lines 3 5 10 HOSTID 44 HOSTID hostidl1l hostid2 hostidn A hostid binds the feature to a particular host or hosts It is a case insensitive string returned by the FLEX m utility Imhostid or by the FLEXible API function lc_hostid A hostid is required for uncounted licenses and is optional for counted licenses Counted licenses are usually bound to the hostid of the machine running the license server in which case the hostid is specified on the SERVER line of the license file or files loaded by the license server A hostid list can be specified Each hostid is space separated quotes surround the entire list e g HOSTID 12345678 FLEXID 6 876d32la HOSTNAME joe If a list of hostids is used the feature is granted on any one of the hostids in the list HOSTID LIST CONSIDERATIONS For uncounted licenses the following line FEATURE 0 uncounted HOSTID hostidl hostid2 hostid3 is equivalent to the set of lines FEATURE f0 uncounted HOSTID hostidl FEATURE f0 uncounted HOSTID hostid2 FEATURE f0 u
57. contains a listing of platform specific and special hostids Vendor defined hostids are discussed in Chapter 15 Vendor Defined Hostid Types The decision to use a particular hostid is made in the license file rather than the FLEX m enabled product However there are occasions when the FLEX m enabled product may want to determine a hostid type specified in a particular FEATURE line for example to detect the usage of special hostid types such as DEMO and ANY The FLEXible API function lc_auth_data called within the product provides this information SEE ALSO e Section 6 4 1 lc_auth_data e Section 8 1 1 1_new_hostid FLEXIm Reference Manual August 2004 25 Types of License Files e Section 8 1 6 lc_free_hostid e Section 3 2 SERVER Lines e Section 3 5 FEATURE INCREMENT Lines e Section D 4 3 Intel Pentium III Hostid HOSTID_INTEL 2 3 Types of License Files The information in the license file affects how the contents are interpreted by FLEXIm The license file supports e Node locked licenses e Demo evaluation licenses e Network licenses either one license server or three server redundant configurations Examples of these types are presented below In addition see the xamples licenses for additional examples Following are license file examples starting with the simplest In the examples the changes from the previous example are in bold text 2 3 1 Simple
58. cumulative number of failed attempts to reconnect to the license server each call to Ip_heartbeat making one attempt In which case applications should at a minimum notify the user of the failure Applications can set a limit to the number of reconnects before exiting In addition applications may want to exit if reconnections succeed more than three or four times in a relatively short period e g ten minutes which may indicate a user restarting the license server in an attempt to acquire extra licenses PARAMETERS LP_HANDLE lp_handie The handle from the lp_checkout call int num_reconnects Pointer to int If null this argument is ignored If non null and the client has just successfully reconnected to the server the return value will be 0 success and num_reconnects is set to the number of times the client has reconnected in the last minutes If this is a large number it may indicate attempted theft Simple API 5 2 5 5 2 6 Simple API Function Descriptions int num_minutes If O this argument is ignored If non zero it s used to detect when a server is being started and stopped many times in a short period which can indicate attempted theft The reporting period is set with num_minutes RETURN int status 0 if successful otherwise it returns the number of failed attempts to reconnect to the server SEE ALSO e Section 7 2 1 LM_MANUAL_HEARTBEAT e Chapter 12 Heartbeats Ip_
59. describes setup and administration of a FLEX m licensing system Typographic Conventions The following typographic conventions are used in this manual e The first time a new term is used it is presented in italics e Commands and path file and environment variable names are presented ina fixed_font e Other variable names are in an italic_fixed_font e API function calls are in a sans serif font Contacting Technical Support Contacting Technical Support Technical Support is available to customers with current support contracts and prospects Please include the following information with your inquiry e Product Name e Product Version e Operating System Name and Version Contact the support center for your area http www macrovision com services support FLEXIm Reference Manual August 2004 XV Contacting Technical Support xvi Introduction 1 1 FLEX m APIs Most of the important functionality and flexibility in FLEX m is contained in the license file all license file attributes are available to all APIs The application program interfaces to FLEX m via a set of functions that request checkout and release checkin licenses of selected feature s There are four major FLEX m APIs available to the developer e Trivial API including both function based and macro based versions e Simple API e FLEXible API e Java API based on the FLEXible API Macrovision recommends using the Trivial API if however
60. feature to the license pool Ic_checkout Requests a license of a feature Ic_errstring Returns an explanatory error string for the most recent error Ic_expire_days Returns the number of days until a license expires Ic_free_job Frees a job allocated with Ic_new_job Ic_heartbeat Sends heartbeat from client application to license server Used for manual heartbeat implementations Ic_new_job Initializes FLEX m and creates a license job Ic_perror Prints an error message to stderr or error message dialog on Windows Ic_set_attr Sets a FLEX m client attribute These and additional functions are documented in this chapter and other functions are documented in Appendix D Obsolete FLEXible API Features It is rare that an application will require the functions in this appendix and care should be used when calling them FLEXIm Reference Manual August 2004 89 FLEXible API Function Descriptions 6 4 6 4 1 90 FLEXible API Function Descriptions Ic_auth_data SYNTAX conf lc_auth_data job feature DESCRIPTION Gets authenticated information corresponding to the specific license file line for a feature that has been checked out This is the only way to retrieve authenticated information for a checked out feature Use a separate call to Ic_auth_data for each checked out feature The following code excerpt demonstrates using this
61. for overdraft for this feature Use lc_auth_data to ensure that you get the CONFIG struct for the license that has been checked out conf 1c_auth_data IC ENS KG_COMPONEN if conf gt package_mask LM_ amp amp conf gt package_mask M_LIC E_PKG_SUITE fi feat conf gt parent_feat if 1c_get_attr job LM_A VD_F 1lc_perror job 154 Controlling Licensing Behavior EATUR E_INFO LM A VDF EATUR T short amp fi E_INFO FLEXible API Attributes set by Ic_set_attr else printf suite overdraft is d n fi overdraft SEE ALso e Section 8 1 7 Ic_get_config e Section 8 1 10 Ic_next_conf e Section 6 4 1 lc_auth_data 7 3 22 LM_A VENDOR ID DECLARE Type Pointer to LM_VENDOR_HOSTID struct Default None This is for supporting vendor defined hostid The struct defines and declares the hostid to FLEX m SEE ALSO e Chapter 15 Vendor Defined Hostid Types e machind Ilmclient h for LM_VENDOR_HOSTID definition e examples vendor_hostid directory 7 3 23 LM_A_VERSION LM_A REVISION Type short Default Version and revision of the libraries you have linked with FLEX m version Cannot be set Only for use with Ic_get_attr 7 3 24 LM_A WINDOWS _MODULE_ HANDLE Windows only Type long Default 0 This is only needed for a specific situation on Windows You
62. freed upon a subsequent call to Ic_feat_list Do not free this data If NULL an error has occurred ERROR RETURNS LM_CANTMALLOC The call to malloc failed LM_NOFEATURE Specified feature not found FLEXIm Reference Manual August 2004 111 FLEXible API Function Descriptions 6 4 9 112 Ic_first_job SYNTAX job 1lc_first_job job DESCRIPTION Ic_first_job is used to find the first job in a list of jobs CODING EXAMPLE LM_HANDLE job job lc_first_job job while job processing job lc_next_job job PARAMETER LM_HANDLE job A pointer to the first job is returned into this parameter ERROR RETURNS None SEE ALSO e Section 6 4 10 Ic_free_job e Section 6 4 17 Ic_new_job e Section 6 4 18 Ic_next_jobQ e Section 11 4 Multiple Jobs FLEXible API FLEXible API Function Descriptions 6 4 10 Ic_free job SYNTAX void lc_free_job job DESCRIPTION Ic_free_job frees the memory associated with a job which has been allocated by Ic_new_job Calls to this function are needed only by an application that uses a large number of jobs over its lifetime Ic_free_job removes everything associated with job this includes any timers memory and licenses For dynamically linked Windows applications or FLEXenabled DLLs it is required to call lc_cleanup after the last call to Ic_free_job PARAMETERS LM_HANDLE job From Ic_new_j
63. function In this example the application obtains the feature line for the feature just checked out in order to process the NOTICE field For this example consider the following feature line from the license file FEATURE f1 demo 1 0 permanent 4 NOTICE ab MX SIGN XXXXXXXXXXXX The code appears as follows in the application CONFIG conf after the call to lc_new_job if 1c_checkout job feature error processing else conf lc_auth_data job feature Use conf gt lc_notice for intellectual property info if conf gt lc_notice 0 a a processing else if conf gt lc_notice 1 b pb processing FLEXible API Note 6 4 2 FLEXible API Function Descriptions PARAMETERS LM_HANDLE job From Ic_new_job char feature The desired feature RETURN CONFIG conf The CONFIG struct or NULL if error The CONFIG struct is defined in the header file lmclient h ERROR RETURNS LM_FUNCNOTAVAIL Vendor keys do not support this function LM_NOFEATURE Feature not found If you want a checkout to depend on information in the license file call Ic_set_attr with LM_A_CHECKOUTFILTER LM_A_CHECKOUTFILTER_EX or LM_A_CHECKOUTFILTERLAST_EX before the call to Ic_checkout SEE ALSO e Imclient h for the CONFIG struct definition e Section 6 4 11 Ic_get_attr e Section 6 4 3
64. have shipped will now be legal so for example if you had shipped a customer a FEATURE line with a count of 5 then upgraded them with a new line with a count of 7 they would now be able to use 12 licenses Also note that license borrowing depends on the INCREMENT line so if you use ls_use_all_feature_lines then license borrowing will not be available to you Advanced FLEXible API Features Advanced Vendor Variables SEE ALso e Section 3 5 FEATURE INCREMENT Lines 8 3 10 Is user lockfile char 1ls_ user _lockfile char NULL By default only one instance of a vendor daemon with the same name can run on the same machine at one time a lock file is used to prevent multiple copies from executing at the same time The default lock file names are UNIX var tmp lockvendor On some systems including DEC Alpha the location is var tmp flexlm lockvendor Windows C flexlm vendor where vendor is the vendor daemon name as on the VENDOR line in the license file To change the location of the lock file set 1s_user_lockfile to the new location If 1s_user_lockfile is NULL the default lock file will be used Express the lock file name as the file s full path name USAGE GUIDELINES FOR VENDOR DAEMON SYNCHRONIZATION e Windows Platforms If one or more vendor daemons involved in the synchronization are pre v8 2 use this mechanism for all daemons in the group If all vendor daemons involved in the sync
65. if reconnection fails after LM_A_ RETRY COUNT attempts If no routine is specified then Ic_perror is called and the licensed application will exit The LM_A_USER_EXITCALL routine is called as follows exitcall feature or with LM_A_USER_EXITCALL_EX exitcallEx job feature vendor_data This callback function is an exit handler it should not return Behavior is undefined if any FLEXIm client routine is called after this exit handler is called If you want to do anything more subtle than exiting do not specify an exit handler function Instead set LM_A_RETRY_COUNT to 1 and specify an LM_A_USER_RECONNECT function which sets a global variable monitor this variable in the mainline code not in a callback function Take appropriate action when the global variable reaches your defined limit LM_A_USER_EXITCALL_EX provides a way to pass vendor defined data to this callback function Behavior is undefined if both LM_A _USER_EXITCALL_EX and LM_A_USER_EXITCALL are set Controlling Licensing Behavior FLEXible API Attributes set by Ic_set_attr CALLBACK PARAMETERS LM_HANDLE job LM_A_USER_EXITCALL_EX only A pointer to the current license job char feature A pointer to the feature name void user_data LM_A_USER_EXITCALL_EX only A pointer to user defined data set via the LM_A_VENDOR_CALLBACK_DATA attribute SEE ALso e Section 6 4 12 Ic_heartbeat e Section 7 3 16 LM_A_RETRY_COUNT
66. in the cache to find the one match that matches borrowdata The initial field of each record sizeof int contains the size in bytes of the record The size of this initial field is included in the count e Remove the matching record from the cache e Cleanup the cache as appropriate Do not attempt to free the borrowdata buffer itself Itis allocated on the stack and will get popped on return from the callback This function is one of the borrow data cache management routines the others being 1s_borrow_init and 1s_borrow_out SEE ALSO e Section 8 3 2 Is_borrow_init e Section 8 3 3 Is_borrow_out Is_borrow_init void 1s_borrow_init char borrowbuf int bufsize default_BorrowInit This callback function e Allocates a buffer of bufsize bytes with malloc The license server subsequently uses free to free the buffer e Initializes borrowbuf with a pointer to a byte array containing the contents of the borrow data cache e Initializes bufsize with the size in bytes of the borrow data cache Advanced FLEXible API Features Advanced Vendor Variables The borrow data cache contains a record with borrow data for each borrowed license The initial field of each record sizeof int contains the number of bytes comprising that record The first byte of the subsequent record immediately follows the last byte of the previous record The license server at start up time calls this function if it
67. int hostid_list HOSTID_ETHER HOSTID_USER int num_ids 2 extern LMHANDLE 1m_job this must be lm_job void init_composite_hostid Pe BY Register the composite hostid ret lc_init_simple_composite job hostid_list num_ids if ret 0 error processing E EF Now anytime FLEXlm refers to HOSTID_COMPOSITE during this job it will be calculated based on both HOSTID_ETHER and HOSTID_USER E FE For your convenience this routine is provided in the SDK distribution as examples composite init_composite c 6 Open plat form makefile ina text editor This example uses a Windows makefile e Add the vendor defined hostid code to the list of EXECS For this example add init_composite obj After the DAEMON section add a section to build init_composite ob3 For example init_composite obj SRCDIR init_composite c CC CFLAGS I h SRCDIR init_composite c e Add init_composite obj to the link line for DAEMON 7 Rebuild your vendor daemon and distribute it to your end user 238 Composite Hostids Creating a Composite Hostid Utility 14 5 Creating a Composite Hostid Utility Because the FLEX m SDK utilities LMTOOLS 1Imuti1 and lmhostidare not able to determine the composite hostid value you need to provide a means for your end user to determine the composite hostid value for the system on which your product runs and for
68. ion ee ee ee ees 18 1 1 3 Migrating to the FLEXible API 18 1 2 FLEXI m Terms and Definitions 005 19 Chapter 2 The License File Overview 0 0 cece ee eee eee nee 23 2 1 Format of the License File 0 0 0 0 0c eee eee 23 2 2 Hostids for FLEX m Supported Machines 25 2 3 Types of License Files 0 0 00 eee eee eee eee 26 2 3 1 Simple Uncounted License 0 0 000008 26 2 3 2 Expiring Demo License 0 0 00 e sees 26 2 3 3 Simple Floating Counted License 27 2 3 4 Floating with Three Server Redundancy 28 2 3 5 Mixed Floating Counted and Uncounted 28 2 4 License ina Buffer 0 0 29 Chapter 3 The License File Syntax 0 0 ee eee eee eee 31 3 1 General Syntax Issues 1 0 enyn e eee ee 32 3 1 1 Comment Lines 0 00 0 eee 32 3 1 2 Line Continuation 0 0 0 eee eee 32 3 2 SERVER Lanes ecos is Gob Oe cs hg ew E 33 33 VENDOR LIME s sene 00 cd aaa Pa cutee Sele Sea 35 3 4 USE_SERVER Line 0 0 eee eee ee 36 3 5 FEATURE INCREMENT Lines 000 36 35L Feature Name oca te A ET 41 3 5 2 Vendor Daemon Name 0 0 0s eee eee eee ee 41 313 Feature Version dates dll ed 41 3 34 Expiration Date s raoe oe A dd 42 3 5 5 Number of Licenses esros naparan eee ee 42 FLEXIm Ref
69. is set By default this callback is defined with an internal implementation that uses an internally defined borrow data cache You can override the internal implementation with your own function that accesses your vendor defined borrow data cache The following code is a sample implementation of this function using the file myBorrowF ile as the vendor defined borrow data cache void myBorrowInit char borrowbuf int bufsize int filesize 0 char filename MAX_PATH myBorrowFile FILE fp NULL bufsize 0 open borrow data file myBorrowFile void fseek fp 0 SEEK_END filesize ftell fp get size of myBorrowFile if filesize there is borrow data to return alloc buffer borrowbuf with filesize number of bytes assumes that record are stored such that the first byte of a subsequent record immediately follows the last byte of the previous record borrowbuf char malloc sizeof char filesize if borrowbuf Copy all data into buffer void fseek fp 0 SEEK_SET fread borrowbuf filesize 1 fp bufsize filesize else there is no borrow data to return FLEXIm Reference Manual August 2004 189 Advanced Vendor Variables borrowbuf NULL bufsize 0 close the borrow data file fclose fp This function is one of the borrow data cache management routines the others being 1s_bo
70. it s stored compressed in the decimal version and the conversion is about 1 1 instead of 1 3 For example VENDOR_STRING 12345 consumes about five characters in the decimal format VENDOR_STRING abcd valid hex characters will also consume about five characters in the decimal format Knowing this you might choose to encode information in the VENDOR_STRING in a numeric format This enhancement only applies to numbers lt Oxffffffff For example VENDOR_STRING 12345678901234 will require about 14 3 42 characters in the decimal format Mixed case hex characters will not be stored efficiently VENDOR_STRING abcD will take about twelve decimal characters instead of five FLEXIm Reference Manual August 2004 63 Decimal Format Licenses 64 FEATURE NAMES ee 99 Avoid underscore For example demo prod_la 10449 31786 63556 56877 09398 10373 137 in feature names it s hard to distinguish from a hyphen c6 99 This is hard to read and if the user mixes up the and _ the license will be invalid Since you also can t use in a feature name this means that feature names won t have any kind of separator Therefore in the example we suggest simply prodla EXPIRATION DATES For non expiring licenses use permanent or 1 jan 0 as the expiration date Some older format but still valid expiration dates are not supported in the decimal format For example 3 mar 0 is func
71. length limit is the same as the FEATURE line length 2048 characters There are no other string size limitations on anything in this file Note that GROUPs can be made arbitrarily large by listing the GROUP more than once FLEX m concatenates such entries FLEXIm Reference Manual August 2004 Decimal Format License Limits 1 through 2 147 483 647 1 through 2 147 483 646 1 through 2 147 483 647 1 through 32767 1 through 2 147 483 647 64 bytes Limited only by the total length of the FEATURE line Approximately 100 bytes Because ASCII text becomes much larger in decimal format a FEATURE line of 100 characters is unreadable and more prone to data entry errors in decimal format Everything but PACKAGE and FEATURESET lines Only officially supported FEATURE names In particular hyphen cannot be converted 273 Ic_set_attr limits B 5 B 6 B 7 274 Ic_set_attr limits LM_A_DISPLAY_OVERRIDE 32 bytes LM_A_HOSTNAME_OVERRIDE 64 bytes LM_A_USERNAME 20 bytes LM_A_CHECKOUT_DATA 32 bytes LM_A_CHECK_INTERVAL gt 20 seconds Other API Limits Maximum length for entire specification of 41 bytes vendor defined hostid LABEL hostid Maximum number of licenses in one 9999 Ic_checkout request Maximum long error message length 1024 bytes length of string returned from Ic_errstring Vendor Daemon Limits NUMBER OF APPLICATIONS PER VENDOR DAEMON When using TCP IP ports each FLEX m ena
72. license generator utility link with the libraries listed in Table 6 10 These libraries are in the plat form directory of your software development kit Additionally refer to the rules for building the Imcrypt license generator in plat form makefile Table 6 10 License Generator Utility Libraries FLEXIm Client Libraries Windows System MT MD Libraries lmgr lib lmgr_md lib oldnames lib libcrvs lib libcrvs_md lib kernel32 1ib libsb lib libsb_md lib user32 1lib flock lib flock_md lib netapi32 1lib advapi32 1lib gdi32 lib comd1g32 1lib comct132 1lib wsock32 1lib For mt libemt lib For md msvcrt lib FLEXIm Reference Manual August 2004 103 FLEXible API Function Descriptions For UNIX platforms Once you have successfully compiled your license generator link with a command similar to the following cc o lic_gen lic_gen o Lplatform liblmgr a libcrvs a libsb a OSLIBS with the following notes e lic genis your license generator utility that incorporates Icryptstr e platformis platform directory in the production software development kit which contains the necessary FLEX m client libraries e S OSLIBS is a list of platform specific libraries Refer to the rules for building the 1Imcrypt license generator in plat form makefile for the list specific to your platform PARAMETERS LM_HANDLE From Ic_init lm_ job char str Set str to a complete valid li
73. m internal and external symbol names to be obfuscated lmstrip 1 where filename Name of the file to process f filename Additional files to process e Do not obfuscate FLEX m external symbol names n Do not obfuscate either FLEX m internal or external symbol names f Obfuscates by replacing each symbol name with a string of random printable characters Each new string is no more than six bytes This is the default action Advanced FLEXIm Topics Security and FLEXIm m Creates a mapfile if it does not exist or use an existing mapfile Default mapfile name is lmstrip map Forces randomized names to be the same across invocations mapfile Uses mapfile to override the default mapfile mapfile name strings A list of vendor specified symbol names in filename to be obfuscated 1 Displays a list of all FLEX m internal and external symbol names to be obfuscated WINDOWS USAGE lmstrip e i v ql m rw mapfile o string_file filename To display a list of all FLEX m internal and external symbol names to be obfuscated lmstrip 1 To display a list of non FLEX m symbol names in filename lmstrip p filename where e Do not obfuscate FLEXIm external symbol names i Do not obfuscate FLEX m internal symbol names v Verbose mode In addition to standard status information displays all symbol names along with their new names that have been obfuscated q Quiet mode All output is suppressed mr
74. nor allows for vendor customization The license manager daemon does allow the license file location and the server to server connection timeout interval to be set by the end user These options are set by command line arguments when starting imgrd 10 1 Imgrd Command Line Syntax 1mgrad is the main daemon program for FLEX m When you invoke Imgra it looks for a license file which contains information about vendors and features The command line syntax for lmgrd is Imgrd c license file list 1 debug_log_path 2 p local x lmdown x lmremove v z help where c license_file_list Use the specified license file s 1 debug_log_path Write debugging information to file debug_log_path This option uses the letter 1 not the numeral 1 Prepending debug_log_path with the character appends logging entries FLEXIm Reference Manual August 2004 203 Imgrd Command Line Syntax 2 p Restricts usage of 1Imdown Imreread and Imremove to a FLEX m administrator who is by default root If there a UNIX group called Imadmin then use is restricted to only members of that group If root is not a member of this group then root does not have permission to use any of the above utilities If 2 p is used when starting lmgrd no user on Windows can shut down the license server with 1mdown local Restricts the 1mdown command to be run only from the same machine where imgrd is running x lmdown D
75. of the combination For example DUP_GROUP UHD means the duplicate grouping is DUP_USER DUP_HOST DUP_DISPLAY so a user on the same host and display will have additional uses of a feature and not consume additional licenses This keyword is valid only with counted licenses FLOAT_OK FLOAT_OK server_hostid Optional field Enables mobile licensing via FLEXid with FLOAT_OK for a particular FEATURE INCREMENT line see the FLEXIm Programmers Guide for more information about mobile licensing This FEATURE INCREMENT line must also be node locked to a FLEXid When FLOAT_OK server_hostid is specified on a FEATURE line e The server_hostid must refer to the same host that appears on the SERVER line of the license file e The license server can only be run on the machine with the hostid that 1mhost id returns equal to the server_hostid specified with FLOAT_OK e A user can run on the license server machine but he can use only the license being served by the license server not the node locked license Otherwise an extra use for each FLOAT_OK license could occur The hostid on the FLOAT_OK FEATURE line must be only a single hostid For multiple dongles use individual FEATURE lines for each dongle HOST_BASED HOST_BASED n Optional field If HOST_BASED appears then licenses can be used only by hosts INCLUDEd for this feature in the end user options file The purpose is to limit the use to a particular number of hosts
76. the KEY information are printed to stderr also on Windows this is logged to flex_err log The diagnostics are enabled by default Macrovision recommends that this be left enabled This will allow us to help you debug your end users problems with error messages more explicit than can t get license In these situations we are unable to help We developed and distributed the FLEXLM_DIAGNOSTICS to enable us and your support people to help your end users more effectively LM_A_DISABLE_ENV Type short Default LM_LICENSE_FILE environment variable enabled If set to a non zero value disable_env will force the FLEX m client functions to disregard the setting of the LM_LICENSE_FILE environment variable It s rare that there s a legitimate reason to use this but it does come up with certain utilities that may explicitly need to ignore the LM_LICENSE_FILE Advanced FLEXible API Features Note 8 2 8 Note Advanced FLEXible API Attributes environment variable It is strongly discouraged that this be used in your applications as many end user sites are familiar with FLEX m and need to assume that LM_LICENSE_FILE will be effective This must be set before LM_A_LICENSE_DEFAULT to be effective LM_A_DISPLAY_OVERRIDE Type char Default No override of display name This value cannot be changed for a job after the initial connection to t
77. to return the license LM_CANTWRITE Cannot send data to license server LM_NOFEATURE The feature specified doesn t match any borrowed items on the client side SEE ALSO e Section 8 3 4 Is_borrow_return_early Ic_check_key SYNTAX status l1lc_check_key job conf code DESCRIPTION Ic_check_key determines if the signature in the CONFIG structure pointed to by conf is valid This function is optional and only for use during license installation it is not used in an application that also calls lc_checkout If authenticated license information is needed without checking out a license use Ic_checkout with the LM_CO_LOCALTEST flag To verify a license file upon installation use code similar to the following example VENDORCODE code lc_new_job amp code feats lc_feat_list w hile feats pos 0 while conf lc_next_conf job feats amp pos if lc_check_key job conf amp code Advanced FLEXible API Features error feats PARAMETERS LM_HANDLE job From Ic_new_job CONFIG conf From Ic_next_conf lc_get_config pointer to From Ic_new_job VENDORCODE code RETURN int status The FLEX m error code or 0 for no error Advanced FLEXible API Functions ERROR RETURNS LM_BADCODE LM_BADPARAM Problem with conf argument LM_FUTURE_FILE a future FLEX m version SEE ALso examples advanced exinstal c Sectio
78. to a struct is given as an argument to Ic_get_attr upon successful return this struct is filled with the appropriate information The following example illustrates the use of both attributes Though Ic_get_config and Ic_next_conf are described in Section 8 1 Advanced FLEXible API Functions one of their legitimate uses is with LM_A_VD_GENERIC_INFO and LM_A_VD_FEATURE_INFO If you are reporting on a feature that has been checked out successfully use Ic_auth_data instead of Ic_next_conf Controlling Licensing Behavior FLEXible API Attributes set by Ic_set_attr tinclude lmclient h include lm_code h include lm_attr h JE Print out GENERIC and FEATURE information for every license file line for a given feature nam void jul vendor_daemon_info LM_HANDL CONFIG conf c LM_VD_GENERIC_INFO gi M_VD_FEATURE_INFO fi int first Le Q CONFIG 0 for lc_next_conf co conf if first get generic da El gi feat conf if lc_get_attr lc_perror else print print print print print Cit tf prin prin print FLEXIm Reference Manual August 2004 3ob char feature job feature amp c conf nf 1c_next_conf job feature amp c mon info job LM_A_VD_GENERIC_INFO short amp gi job LM_A_VD_GENERIC_INFO conn timeout din gi con
79. uncounted HOSTID 778da450 SIGN DB5CC00101A7 For the above PACKAGE and FEATURE line note the following FEATURE c1 demo FEATURE c2 demo FEATURE c3 demo FEATURE c5 demo FEATURE c6 demo The FEATURE line enables the PACKAGE line The each component inherits information from the enabling FEATURE line In this example they all inherit the expiration date number of licenses and hostid The enabling FEATURE line must match the name version and vendor name of the PACKAGE line The PACKAGE line can be shipped with the product since it contains no customer specific fields PACKAGE lines can be shipped in a separate file that never needs end user editing so long as the file is include in the license file list These PACKAGE and FEATURE lines together are a more efficient way of delivering the following 7 FEATURE lines 0 permanent uncounted HOSTID 778da450 SIGN D03F02432106 0 permanent uncounted HOSTID 778da450 SIGN 99375F40FD85 0 permanent uncounted HOSTID 778da450 SIGN 68FAC130DB90 0 permanent uncounted HOSTID 778da450 SIGN 5A91D6EFB68C 0 permanent uncounted HOSTID 778da450 SIGN 8F75798EB975 1 1 1 FEATURE c4 demo 1 0 permanent uncounted HOSTID 778da450 SIGN D3D617E2075A 1 1 1 FEATURE c7 demo 0 permanent uncounted HOSTID 778da450 SIGN 790545E90575 PACKAGE SUITE_RESERVED Example With the OPTIONS SUITE_RESERVED keyword package component licenses are granted to a fixed number of users at any one time
80. vendor defined data set via the LM_A_VENDOR_CALLBACK_DATA attribute If LM_A_RETRY_COUNT is set to a value lt 0 then the reconnect handler will not be called SEE ALSO e Section 6 4 12 Ic_heartbeat e Section 7 3 5 LM_A_CHECK_INTERVAL e Section 7 3 18 LM_A_USER_EXITCALL LM_A_USER_EXITCALL_EX e Section 8 2 17 LM_A_VENDOR_CALLBACK_DATA 150 Controlling Licensing Behavior FLEXible API Attributes set by Ic_set_attr 7 3 20 LM_A USER_RECONNECT_DONE Note LM_A USER RECONNECT DONE EX Type Pointer to a function returning int Return value unused Default None DESCRIPTION The function pointer LM_A_USER_RECONNECT_DONE or the extended version LM_A_USER_RECONNECT_DONE_EX is set to point to a callback routine This routine is called when reconnection is successfully completed The LM_A_USER_RECONNECT_DONE handler is called as follows reconnect_done feature tries total_attempts interval or for LM_A_USER_RECONNECT_DONE_ EX reconnect_doneEx job feature tries total_attempts interval vendor_data LM_A_USER_RECONNECT_DONE_EX provides a way to pass vendor defined data to this callback function Behavior is undefined if both LM_A_USER_RECONNECT_DONE_EX and LM_A_USER_RECONNECT_DONE are set CALLBACK PARAMETERS LM_HANDLE job LM_A_USER_RECONNECT_DONE_EX only A pointer to the current license job char feature Feature name int tries Number of atte
81. write granted forat most two distinct users 3 ul or u2 write denied Maximum number of write licenses exceeded 4 u3 paint denied Maximum number of distinct users exceeded 5 ul or u2 paint granted Two paint licenses available 6 ul or u2 paint granted forat most two distinct users FLEXIm Reference Manual August 2004 59 PACKAGE Lines 60 eses Requested Checkout User q Result Explanation Feature Attempt 7 ul or u2 paint denied Maximum number of paint licenses exceeded 8 u3 draw denied Maximum number of distinct users exceeded 9 ul or u2 draw granted Two draw licenses F available for at 10 ul or u2 draw grante most two distinct users 11 ul or u2 draw denied Maximum number of draw licenses exceeded Note that components are not reserved for a given user by virtue of that user being granted one component In the example depicted above user ul getting both of the grants for paint does not reserve the rest of the components for him This paradigm allows user u2 to get the remaining four grants two for paint and two for draw SHARING A FLOATING LICENSE Without feature or suite duplicate grouping constraints specified in the components of package suite a floating license is shared among the components of the package regardless of the number of users Consider the following example PACKAG E office demo 1 0 COMPON OPTIONS SUITE SI
82. 0 HOSTID e Chapter 15 Vendor Defined Hostid Types VENDOR Line VENDOR vendor vendor_daemon_path options options_file path port port The VENDOR line specifies the name and location of a vendor daemon as well as the location of the end user s options file vendor Name of the vendor daemon used to serve at least some feature s in the file vendor_daemon_path Path to the executable for this daemon If blank Imgrd s PATH environment variable plus the current directory is used by lmgrd to find the daemon process to start options _ file path Path to the end user options file for this daemon If unspecified the vendor daemon will look for a file called vendor opt where vendor is the vendor daemon name in the same directory where the license file is located If found this file is used as the end user options file port Vendor daemon port number The default if port is not specified is chosen by the operating system at run time Sites with Internet firewalls need to specify the port number the daemon uses If a port number is specified on the VENDOR line there may be a delay restarting the vendor daemon until all the clients have closed their connections to the vendor daemon FLEXIm Reference Manual August 2004 35 USE_SERVER Line Note 3 4 3 5 36 A port number must be specified in the VENDOR line when you are connecting to the vendor daemon through a firewall UNIX E
83. 0316207 result in 3 licenses for v1 0 the original 4 licenses for v2 0 and 2 licenses for v3 0 taken from the original group of five v1 0 licenses Now consider this scenario INCREMENT f1 demo 1 0 1 jan 2005 5 SIGN 9BFACO3164ED INCREMENT f1 demo 2 0 1 Jjan 2005 4 SIGN 8BF3fb031643 UPGRADE f1 demo 1 0 3 0 1 Jan 2005 10 SIGN afb303162056 This results in 9 licenses for v3 0 5 v1 0 plus 4 v2 0 all upgraded to v3 0 and 1 unused upgrade LICENSE POOL CONSIDERATIONS Multiple UPGRADE lines applied to a set of FEATURE and INCREMENT lines can have the result of creating separate license pools where they did not previously exist Subsequent checkout requests are subject to multiple license pool restrictions For example INCREMENT 1 demo 1 0 1 jan 2005 8 SIGN 9BFAC03164ED UPGRADE f1 demo 1 0 2 0 1 jan 2005 5 SIGN afb303162056 UPGRADE f1 demo 1 0 3 0 1 jan 2005 3 SIGN afb303162056 This upgrade scenario results in breaking up the one license pool of 8 licenses for v1 0 into two license pools one with 5 licenses for v2 0 and one with 3 licenses for v3 0 A checkout request of 6 licenses for v1 0 is denied because neither pool has 6 licenses whereas before the upgrade it would be granted because of the single pool of 8 licenses for v1 0 FLEXIm Reference Manual August 2004 51 PACKAGE Lines 3 7 PACKAGE Lines PACKAGE package vendor pkg_ version COMPONENTS pkg_list OPTI
84. 192 ls_use_featset 299 ls_user_initl 232 Is_user_init2 232 Is_user_init3 233 ls_user_lockfile 193 ls_user_lockfile2 193 ls_vendor_msg 233 and Ic_vsend 134 LSAPI v1 1 266 Isvendor c 227 and Ic_heartbeat 118 and Ic_vsend 134 It_checkin 67 It_checkout syntax 67 It_errstring 69 It_heartbeat 69 It_perror 70 It_pwarn 70 It_warning 71 M Macintosh platform notes 251 MAX_OVERDRAFT 200 MAX_VENDOR_CHECKOUT_DATA 176 MINIMUM 45 multiple jobs 209 multithreaded applications 208 FLEXIm Reference Manual August 2004 315 N node locked license definition 21 NOTICE 45 O options file definition 21 limits 273 path on VENDOR line 35 OPTIONS SUITE 53 OPTIONS SUITE_RESERVED 53 OVERDRAFT 45 and LM_A_VD_FEATURE_INFO 154 detecting for suites 154 OVERDRAFT detection 200 P PACKAGE line 52 and demo licensing 198 COMPONENTS 52 OPTIONS SUITE 53 OPTIONS SUITE_RESERVED 53 305 package suite bundle 58 sharing components 59 unlimited component usage 58 pclose debugging 247 PERROR 70 platform notes Hewlett Packard 252 IBM 252 Linux 252 Macintosh 251 SCO 255 SGI 253 Solaris 251 Windows 257 PLATFORMS 45 policy modifiers 138 port SERVER line 34 VENDOR line 35 preface xiii PWARN 70 R redundant license servers license file list 206 TCP port delay 251 three servers 206 report log file 199 report log file definition 21 RESERVE and duplicate grouping 97 restricting access Imdown 20
85. 2 15 LM_A_RETRY_CHECKOUT 0 186 8 2 16 LM_A_USER_OVERRIDE 0 0 0 0 0 0005 186 8 2 17 LM_A_VENDOR_CALLBACK_ DATA 186 8 3 Advanced Vendor Variables o o oooooooooo o o 187 8IL A eke ties alk te acd paces 188 8 3 2 Is Dorrow nit Bu eee Se es RE os 188 8 3 3 As NE i ae 190 8 3 4 Is_borrow_return_early 20 0 0 cece eee 191 8 3 5 AS CONN TIMEOUt i een ete wie ww ee eA eee 191 8 3 6 ls_do_checkroot UNIX Only 04 191 8 3 7 Is_dump_send_data 0 0 cece eee y 192 8 3 8 ls _hud_hostid_case_sensitive 0 000 eee 192 8 3 9 ls_use_all feature_lines o ooooooooo o o 192 3 10 Is user locktile ui bets ah ta ees 193 8 3 11 Is_user_lock Windows only oo oo ooocooooooo o 193 8 4 Advanced License File Features oo oooooooooooooo o 195 8 41 CAPACITA aii sad 195 Chapter 9 License Models uti nse srne ta tr ti as 197 9 1 Demo Licensing scr esre ecrsci secerni inier ee 197 9 1 1 Limited Time Uncounted Demos ooooo o o 197 9 1 2 Limited Functionality Demos 198 9 2 Lenient Licensing Report Log and OVERDRAFT 199 9 2 1 FLEX m Report Log File oco oooooocoocoocoooo 199 9 2 2 OVERDRAFT Detection 00 00 200 9 3 Mobile Licensing wi es oe ena aia nt opi hea ina es 201 Chapter 10 The License Manager Daemon 0 0 0000 5 203 10 1 I
86. 4 Imremove 204 Imreread 204 RS 6000 252 S SCO platform notes 255 SERVER line host 33 hostid 34 Internet hostid 34 port 34 syntax 33 server node configuration 205 setting license file location 93 TCP port delay 251 SGI platform notes 253 sgi64 254 SIGALRM debugging 247 SIGN 46 signature 46 and lc_check_key 160 316 FLEXIm Reference Manual August 2004 and LM_BADCODE 98 and LM_LGEN_VER 145 definition 21 SIGPIPE debugging 247 Simple API 73 example application 207 license policies 137 license policy modifiers 138 Impolicy h 73 Ip_checkin 74 Ip_checkout 75 Ip_errstring 77 Ip_heartbeat 78 Ip_perror 79 Ip_warn 79 Ip_warning 80 overview 17 site license 97 sleep debugging 247 SN 46 sockets number used by license server 274 Solaris platform notes 251 sort 49 specifying license in application 29 START 47 starting Imgrd 203 Windows 205 subnet limits 275 suite detecting OVERDRAFT in 154 SUITE_DUP_GROUP 47 57 SUPERSEDE 47 system debugging 247 T TCP and lc_checkin 92 and LM_A_TCP_TIMEOUT 148 TCP port delay setting 251 technical support xv term Xiv Terminal Server support 48 258 this_host and lc_convert 162 TIMEOUT and Ic_heartbeat 118 and lc_idle 123 setting 230 Trivial API CHECKINQ 67 CHECKOUTO 67 description 65 ERRSTRING 69 example application 207 HEARTBEAT 69 license policies 137 license policy modifiers 138 It_checkin 67 It_checkout 67 It_errstrin
87. A request for 5 licenses for version v1 0 is denied because neither pool has 5 licenses FEATURE INCREMENT EXAMPLE To illustrate the difference between FEATURE and INCREMENT consider these feature lines FEATURE f1 demo 1 0 permanent 4 FEATURE f1 demo 2 0 permanent 5 They result in four licenses for v1 0 or five licenses for v2 0 depending on their order in the file Now consider INCREMENT f1 demo 1 0 permanent 4 INCREMENT f1 demo 2 0 permanent 5 These result in four licenses for v1 0 and five licenses for v2 0 and below being available giving a total of nine licenses for 1 e INCREMENT lines must differ in some way otherwise only one is used COUNTED vs UNCOUNTED To contrast counted with uncounted licenses consider the following FEATURE line FEATURE f1 demo 1 0 1 jan 2005 uncounted HOSTID DEMO SIGN 123456789012 The License File Syntax 3 5 1 3 5 2 3 5 3 FEATURE INCREMENT Lines This feature has unlimited usage on any hostid requires no license server and 1s therefore could be a complete license file by itself It also happens to be an expiring license and will not allow use of the feature after 1 jan 2005 In contrast because it is counted the following feature requires a license server with a vendor daemon named demo FEATURE f1 demo 1 0 permanent 5 HOSTID INTERNET 195 186 SIGN 123456789012
88. API FLEX m Java API FLEX m Visual Basic API LSAPI a proposed standard FLEXIm is the only licensing system available which supports all six APIs A 1 The FLEX m Trivial and Simple APIs These APIs are suitable for most applications and are robust and easy to implement See Chapter 4 Trivial API and Chapter 5 Simple API for complete information on these two APIs A 2 The FLEX m FLEXible API The FLEXible API has evolved since 1988 with the input of most of the major software vendors in the UNIX software industry The goal of the FLEXible APT is to give you your choice of licensing models in an easy to implement robust package The FLEXible API is documented in Chapter 6 FLEXible API FLEXIm Reference Manual August 2004 265 LSAPI v1 1 A 3 Note 266 LSAPI v1 1 The LSAPI interface a licensing API first proposed in May 1992 was designed by a consortium of software vendors with participation from several licensing system vendors The main claim to fame of this interface is that it attempts to provide a solution whereby the end user can choose the license server product from the licensing system vendor of their own choice While the LSAPI seems to be a simple API it hides the fact that your code will increase in complexity in order to solve the problem of the replaceable license server since both the license server and the licensing system library are in theory replaceable by the end use
89. AT Provides an programming interface to the Imborrow functionality LM_A_LF LIST Lists all license files searched for features LM_A_VD_GENERIC_INFO Retrieves information from the LM_A_VD_FEATURE_INFO vendor daemon LM_A_VERSION Retrieves information regarding LM_A_REVISION the version and revision of the FLEX m client libraries 86 FLEXible API 6 2 5 Error and Warning Reporting FLEXible API Functions by Category These functions provide a way to report errors and warnings from the licensed application to the user These functions and attributes are listed in Table 6 6 Table 6 6 Error and Warning Reporting Function or Attribute Name Description Functions Ic_err_info Used for internationalization Ic_errstring Returns the FLEX m error string for the most recent FLEX m error Ic_perror Prints a FLEX m error message to stderr on UNIX and to a message box on Windows Attributes LM_A_LONG_ERRMSG Presents error messages in the long format LM_A_PERROR_MSGBOX Windows Only Presents the error message in an error dialog box LM_A_WINDOWS_MODULE_HAN DLE Windows only Enables dialogs and error messages to be displayed properly used with DLL only FLEXIm Reference Manual August 2004 87 FLEXible API Functions by Category 6 2 6 License File Installation Vendors may want to supply a utility along with their FLEX m licensed applicatio
90. CENSE_DEFAULT LM_A_VAL_TYPE licpath where 1icpathis the same value as the last argument to CHECKOUT or Ip_checkout 4 Change the CHECKOUT or Ip_checkout call to lc_checkout lm_job feature 1 0 1 LM_CO_NOWAIT amp code LM_DUP_NONE SEE ALSO e Example code in machind 1lmflex c 18 Introduction FLEXIm Terms and Definitions 1 2 FLEX m Terms and Definitions The following terms are used as defined to describe FLEX m concepts and software components Client application Counted license Daemon Debug log file Feature Feature line An application program requesting or receiving a license A license with a non zero license count A license server is required to manage a counted license Counted licenses usually float on a network A process that serves clients Sometimes referred to as a server or service process One or more ASCII text files written by the license server daemons 1Imgrd and the vendor daemons it manages A debug log file contains status and error messages useful for debugging the license server Any functionality that needs to be licensed The meaning of a feature will depend entirely on how it is used by an application developer For example a feature could represent any of the following e An application software system consisting of hundreds of programs e A single program regardless of version e A specific version of a progr
91. DEMO for this type of evaluation and Ic_auth_data is the correct function to use CONFIG conf outline of C source LM_HANDLE Job lc_new_job amp job rc lc_checkout job feature if rc return rc error handling conf lc_auth_data job feature if conf gt idptr amp amp conf gt idptr gt type HOSTID_DEMO it s a demo license disable some functionality SEE ALSO e Section 3 5 FEATURE INCREMENT Lines e Section 3 7 PACKAGE Lines e Section 6 4 1 lc_auth_data e Section 7 2 3 LM_CHECK_BADDATE e Section 13 2 2 Is_a_check_baddate Lenient Licensing Report Log and OVERDRAFT More and more companies prefer licensing that does not deny usage but bills customers for their usage FLEX m Report Log File A FLEXIm report log file which is enabled with Imswitchr and or an end user options file REPORTLOG entry provides a relatively secure method of tracking end user usage See the FLEXIm End Users Guide for more information about starting and managing a report log file The report log file can be used for billing customers for their usage A common method for doing this is to provide a FEATURE line with an OVERDRAFT OVERDRAFT usage is logged to the REPORTLOG file which is then read by FLEXbill from which an invoice can be generated FLEXbill is a separate product available from Macrovision ADVANTAGES The advantages of this system inc
92. EATURE INCREMENT PACKAGE and UPGRADE lines from all the license files The combined license file can be located in the default location usr local flexlm licenses license dat on UNIX platforms and C flexlm license dat on Windows or in any convenient location with the end user using the LM_LICENSE_FILE environment variable or license finder or multiple copies can be located at fixed locations as required by the various software vendors The user should leave a symbolic link to the original license file in the locations where each software package expects to find its license file In practice sites that have experienced system administrators often prefer to combine license files However sites with relatively inexperienced users and no system administrator usually do better leaving the files separate CASE 2 PRODUCTS USE DIFFERENT LICENSE SERVER NODE S In this case separate license files will be required one for each distinct set of license servers The license files can then be installed in convenient locations and the user s LM_LICENSE_FILE environment variable would be set as follows setenv LM_LICENSE_FILE lic_pathi lic_path2 lic_pathn When products from different vendors use different versions of FLEX m always use the latest versions of lmgrd and the 1mutil utilities FLEXIm Reference Manual August 2004 249 FLEXIm Version Compatibility 16 4 250 The la
93. End Users Guide for information about expected and special hostids and Chapter 15 Vendor Defined Hostid Types for vendor defined hostids WARNING If the INTERNET hostid is used on the SERVER line wildcards should not be allowed in the IP address If wildcards are used the customer could easily start license managers on more than one node and obtain extra licenses TCP port number to use This can be edited by the license administrator If not specified FLEX m will automatically use the next available port number in the range 27000 27009 Applications when connecting to a server try all numbers in the range 27000 27009 The port number is required if the license is for a three server redundant license server Using a port number in the range 27000 27009 is recommended when specifying a port number SERVER lines specifying servers in a three server redundant license server system configuration require a port number to be specified Macrovision recommends using port numbers outside the range of 27000 through 27009 The SERVER line must apply to all lines in the license file It is permitted to combine license files from different vendors but only if the SERVER hostids are identical in all files that are to be combined A license file list can be used if hostids are not identical but refer to the same machine 34 The License File Syntax 3 3 VENDOR Line SEE ALSO e FLEXIm End Users Guide e Section 3 5 1
94. GEN_VER 94 will be generated Attempt to generate license with incompatible attributes e The FEATURE line will be left as is without replacing the signature with a correct one SEE ALSO e Section 6 4 4 lc_cryptstrQ 7 3 12 LM_A_LINGER Type long Default 0 no linger This option controls the license linger time for your application Any checkout performed after setting LM_A_LINGER to a non zero value will cause the license to be held by the vendor daemon for the specified number of seconds after either a checkin or your process exits The vendor daemon checks for lingering licenses only once per minute which will limit the granularity of this setting FLEXIm Reference Manual August 2004 145 FLEXible API Attributes set by Ic_set_attr SEE ALSO e Section 11 2 Lingering Licenses 7 3 13 LM_A_LONG_ERRMSG 146 Type int Default True The default is long error messages Error messages can be presented in a long more descriptive format The new format contains embedded newline characters which some applications may not be able to handle or may need special handling Applications will often find it useful to present the short error message first and then long error message upon user request This can be done thus lc_set_attr job LM_A_LONG_ERRMSG LM_A_VAL_TYPE 0 error occurs lc_perror job user requests long error message lc_set_attr job LM_A_LONG_ERRMSG LM_A
95. GN 005 FEATURE The License File Syntax ENTS write paint draw 04091605D office demo 1 0 permanent 1 SIGN DB5CC00101A7 3 8 Decimal Format Licenses This license file defines a package suite via OPTIONS SUITE on the PACKAGE line named office with three components write paint and draw One license is available and shared among the three components Once the license is consumed for one of the components no further licenses are available for checkout This concept is illustrated in the following table License Requested Checkout User q Result Explanation Feature Attempt 1 any write paint granted One license is or draw available for any one of the components 2 any write paint denied Maximum number of or draw licenses exceeded Decimal Format Licenses Licenses can be represented in decimal format to make license delivery easier for customers without access to email Decimal has the advantage that it s simpler to type in and often the licenses are much shorter To generate a decimal format license use the decimal argument for imcrypt or makekey To convert an existing license to decimal use Imcrypt decimal or lminstall i infile o outfile odecimal If needed decimal lines can be mixed with readable format lines in a license file End users will normally use the Iminsta11 command to install decimal format licenses Note that Iminstal
96. LE 205 automatic reconnection 149 command line syntax 203 definition 21 detecting daemon death 142 limits 275 overview 203 starting debug log 203 starting on Windows 205 Imgrd opt 262 Imhostid 25 Impolicy h Simple API 73 Imremove and lingering licenses 291 disabling 204 262 restricting access 204 Imreread restricting access 204 Imsimple c 207 L L L L L L 314 FLEXIm Reference Manual August 2004 Imstat and LM_A_CHECKOUT_DATA 178 Ic_userlist 133 Imstrip and binaries 214 and other FLEXIm libraries 215 and UNIX libraries 215 overview 212 logging uncounted licenses 28 long license key 300 Ip_checkin 74 Ip_checkout license file path 75 syntax 75 Ip_errstring 77 Ip_heartbeat 78 Ip_perror 79 Ip_pwarn 79 Ip_warning 80 Ipthread 251 Ipthreads 251 252 ls_a_behavior_ver 228 ls_a_check_baddate 228 ls_a_license_case_sensitive 228 ls_a_Ikey_long 299 Is_a_lkey_start_date 299 Is_attr h 231 Is_checkout and 1s_outfilter 231 ls_compare_vendor_on_increment 228 ls_compare_vendor_on_upgrade 228 ls_conn_timeout 191 ls_daemon_periodic 229 ls_do_checkroot 191 ls_dump_send_data 192 ls_enforce_startdate 299 Is_get_attr and ls_outfilter 231 ls hud_hostid_case_sensitive 192 Is_incallback 229 Is_infilter 230 ls_min_Imremove 230 ls_minimum_user_timeout 230 and Ic_heartbeat 118 Is_outfilter 230 ls_show_vendor_def 232 and LM_A_CHECKOUT_DATA 178 Is_tell_startdate 299 ls_use_all_feature_lines
97. LTERED 53 284 LM_CI_ALL_FEATURES and Ic_checkin 92 LM_CLOCKBAD 34 282 LM_CO_LOCALTEST and lc_checkout 95 LM_CO_NOWAIT and lc_checkout 94 Ic_status 131 LM_CO_QUEUE and lc_checkout 94 LM_CO_WAIT and lc_checkout 94 LM_COMPOSITEID_INIT_ERR 126 294 and lc_init_simple_composite 168 LM_COMPOSITEID_ITEM_ERR 127 294 and lc_init_simple_composite 168 LM_CRYPT_DECIMAL 105 LM_CRYPT_FORCE 105 LM_CRYPT_IGNORE_FEATNAME _ ERRS 105 LM_CRYPT_ONLY 105 LM_DATE_TOOBIG 49 284 LM_DEFAULT_SEEDS 91 290 and lc_init 125 and Ic_new_job 128 LM_DUP_DISP 96 LM_DUP_HOST 96 LM_DUP_NONE 96 LM_DUP_SITE 97 LM_DUP_USER 96 LM_DUP_VENDOR 96 and LM_A_CHECKOUT_DATA 177 LM_ENDPATH 74 287 LM_EXPIRED_KEYS 50 and lc_init 125 and Ic_new_job 128 LM_EXPIREDKEYS 50 284 LM_FAILSAFE 138 LM_FEATCORRUPT 36 282 LM_FEATEXCLUDE 38 282 LM_FEATNOTINCLUDE 39 282 LM_FEATQUEUE 35 282 and Ic_checkout 99 and Ic_status 132 LM_FLEXLOCK 139 LM_FLEXLOCK2CKOUT 113 292 LM_FLOATOK_ONEHOSTID 121 293 LM_FUNCNOTAVAIL 45 283 and Ic_auth_data 91 and Ic_checkout 99 312 FLEXIm Reference Manual August 2004 and lc_hostid 123 and lc_set_attr 130 and Ic_shutdown 172 and Ic_userlist 134 LM_FUTURE_FILE 90 289 and Ic_check_key 161 LM_HOSTDOWN 96 291 LM_INTERNAL_ERRORS 76 287 Im_isres 134 LM_LENIENT 138 LM_LGEN_VER 94 290 LM_LIBRARYMISMATCH 66 286 an
98. Linux platform e Incompatible executables Executables built and linked on Redhat v4 are not fully forward compatible with Redhat 5 or 6 They may start to run but may later crash with indecipherable causes e Incompatible object files Object files o created on Redhat v4 or v5 and moved to a Redhat v6 system will not link correctly on Redhat v6 If all the object files are fully linked on Redhat v5 the v5 executable will run fine on Redhat v6 e Unexplained problems We have customers that have reportedly not been able to build or run the FLEX m kit for Redhat v6 despite uname a indicating that these customers are using the same Redhat v6 that Macrovision uses to build FLEXIm In these rare cases we have not been able to resolve the situation and are not aware of what causes the problem 17 6 SGI SGI has a variety of CPUs operating systems and compiler switches that are mutually incompatible To explain it s useful to first understand the different CPUs operating systems and switches OPERATING SYSTEMS IRIX 6 5 64 bit OS supports 64 and 32 bit applications MIPS CHIPS MIPS1 First MIPS chip The chip itself is no longer supported by SGI but it s possible to generate binaries that run on this chip R1000 systems MIPS2 Not much is known about MIPS2 and it s not relevant anyway MIPS3 32 and 64 bit binaries R4000 and R6000 systems MIPS4 Improved 64 bit support R8000 and R10000 systems FLEXIm Reference
99. M_HANDLE job job lc_first_job job while job processing job lc_next_job job DESCRIPTION Ic_next_job is used to walk the list of jobs This only works properly if all calls to lc_new_job have a pointer to the current job as the first parameter PARAMETERS LM_HANDLE job Current job FLEXible API FLEXible API Function Descriptions RETURN LM_HANDLE job Next currently active job or LM_HANDLE 0 if end ERROR RETURNS None SEE ALSO e Section 6 4 9 Ic_first_job e Section 6 4 10 Ic_free_jobQ e Section 6 4 17 Ic_new_job e Section 11 4 Multiple Jobs 6 4 19 Ic_perror SYNTAX void lc_perror job string DESCRIPTION Prints a FLEX m error message in the same format as the UNIX function perror e g string FLEX1lm error string If a system error has also occurred it will be included in the message On Windows systems a dialog of type MB_OK will be displayed with the FLEX m error message The FLEX m error messages are available by calling Ic_errstring PARAMETERS LM_HANDLE job From Ic_new_job char string The first part of the error message as above RETURN None SEE ALso e Section 6 4 5 lc_err_info FLEXIm Reference Manual August 2004 129 FLEXible API Function Descriptions e Section 6 4 6 Ic_errstring e Section 7 3 13 LM_A_ LONG ERRMSG 6 4 20 Ic_set_attr SYNTA
100. Manual August 2004 253 SGI COMPILER SWITCHES ON IRIX 6 5 032 It is the old 32 bit object format n32 Native to IRIX 6 5 it is the new 32 bit format 64 Native to IRIX 6 5 64 bit OTHER COMPILER SWITCHES xgot If your application exceeds 64 000 global variables you must compile and link with objects that have this flag if you need this use the libraries with the _xgot suffix We provide two SGI directories sgi32_u6 32 bit IRIX 6 5 liblmgr a n32 or liblmgr_032 a 032 MIPS3 libraries run on MIPS4 systems Requires FLEX m sgi vendor key sgi64_u6 64 bit 64 IRIX 6 5 liblmgr a MIPS3 libraries run on MIPS4 systems Requires FLEX m sgi64 vendor key FLEXLm VENDOR KEYS FOR SGI sgi All SGI 32 bit applications including sgi32_u6 sgi64 All SGI 64 bit applications including sgi64_u6 SGI ORIGIN SYSTEMS These modular systems can have more than one hostid Imhostia will report all the hostids for these systems A license should be generated for only one of these hostids 254 UNIX Platform Specific Notes SCO 17 7 SCO Part of the install_flexlm ftp install scripts may fail on SCO systems It is not difficult to install without the scripts Edit the machind 1m_code h file to put in the correct VENDOR_KEYs obtained from Macrovision and LM_SEEDs 32 bit numbers you make up that make license files unique and VENDOR_NAME Then if it s not an evaluation copy in the sco
101. ONS SUITE SUITE_RESERVED SUP ERSE DE p1 p2 ISSUED date SIGN pkg_sign where package vendor pkg_version pkg_sign pkg_list Name of the package The corresponding FEATURE INCREMENT UPGRADE line must have the same name Name of the vendor daemon that supports this package VENDOR_NAME in 1m_code h Optional version of the package If specified the corresponding FEATURE INCREMENT UPGRADE line must have the same version Signature generated by one of the license generators makepkg lmcrypt or the vendor s customized license generator A space separated list of components The format of each component is feature version num_lic The package must consist of at least one component version and num_lic are optional and if left out their values come from the corresponding FEATURE INCREMENT UPGRADE line num_lic is only legal if OPTIONS SUITE is not set Examples COMPONENTS compl comp2 comp3 comp4 COMPONENTS apple 1 5 orange pear 2 0 4 52 The License File Syntax PACKAGE Lines OPTIONS SUITE This is what distinguishes a package suite from a package used to facilitate distribution With OPTIONS SUITE the package FEATURE is checked out in addition to the component feature being checked out See Section 3 7 3 PACKAGE SUITE Example for more details OPTIONS Reserves a set of package components Once one SUITE
102. R tien bos ada Isai check baddate comia Is_a_license_case_sensitive 0 0 ccc cece eee ls_compare_vendor_on_increment and ls_compare_vendor_on_upgrade 228 13 2 5 Is_daemon_periodic 0 0 cece cee eee 13 267 ancal back a tra atada stato dci 132 7 AAA 6 Oe Eee ee bs Ree Be 13 2 8 Is_min_Imremove 0 0 c ccc ccc cee eee eee 13 2 9 Is_minimum_user_timeout 0 00 0 ee eee 132 107 As QUIE a rd aa bas 13 2 11 1s_show_vendor_ def 0000 130212 CIS USE itl ject see A ata oe cer as Won ddr 133213 CAS USC ANID 4 os whale nel enc aos 1332 04 Us SCOCIDICS 6 esis 05 sad ade Gods la el 13 215 18 Vendor Msg wii nea eee eas ena ina tain Chapter 14 Composite Hostids 0 cece eee t4 1 Overview itr in pe ven beds ib de GPS ston go boca hoa 14 2 Defining a Composite Hostid 0 0 0 0 0 eee ee eee FLEXIm Reference Manual August 2004 14 3 Initializing a Composite Hostid in Your Application 14 4 Initializing a Composite Hostid in Your Vendor Daemon 14 5 Creating a Composite Hostid Utility o ooo o 14 6 Providing a Composite Hostid License Chapter 15 Vendor Defined Hostid Types 0 00 ennen 15 1 COVE Vi Wisin Oa av ed nde wee ba wee A Mee es ae 15 2 Editing Source Files Gess poor ad ne 15 3 Test the Vendor Defined Hostid o ooo oo oocoocoooo o o 15 4 Additional Steps for Production
103. R_MSGBOX 147 PROMPT_FOR_FILE 147 _A RECONNECT_DONE and Ic_heartbeat 117 _A RETRY_CHECKOUT 186 M_A_RETRY_COUNT 147 and Ic_heartbeat 117 M_A_RETRY_INTERVAL 147 LM_A_REVISION 155 LM_A_TCP_TIMEOUT and Ic_heartbeat 118 LM_A_USE_START_DATE 298 LM_A_USER_EXITCALL 148 and Ic_heartbeat 117 LM_A_USER_OVERRIDE 185 186 LM_A_USER_RECONNECT 149 and Ic_heartbeat 117 LM_A_USER_RECONNECT_DONE 151 LM_A_USER_RECONNECT_DONE_ el a e E ea e sis lt lt lt 310 FLEXIm Reference Manual August 2004 EX 151 LM_A_VAL_TYPE and lc_set_attr 130 LM_A_VD_FEATURE_INFO 152 and lc_get_attr 115 and OVERDRAFT 200 LM_A_VD_GENERIC_INFO 152 and lc_get_attr 115 LM_A_VENDOR_CALLBACK_ DAT A 186 LM_A_VENDOR_ID_DECLARE 155 LM_A_VERSION 155 LM_A_WINDOWS_MODULE_HAND LE 155 LM_BAD_TZ 71 287 and Ic_init 125 and Ic_new_job 127 LM_BAD_VERSION 77 288 and Ic_checkout 99 LM_BADCHECKSUM 59 285 LM_BADCODE 8 278 and lc_check_key 161 and Ic_checkout 98 debugging hints 248 LM_BADCOMM 12 279 and lc_remove 171 and Ic_userlist 134 and Ic_vsend 135 LM_BADDATE 11 278 LM_BADDECFILE 99 291 LM_BADFEATSET 55 285 LM_BADFILE 2 277 and Ic_get_config 165 LM_BADHANDSHAKE 33 282 and Ic_checkout 98 LM_BADHOST 14 279 LM_BADKEYDATA 44 283 and Ic_init 125 and Ic_new_job 127 LM_BADPARAM 42 283 and Ic_borrow_return 160 and Ic_check_key 161 and Ic_checkout 98
104. Reference Manual August 2004 Ic_timer 297 and debugging 247 Ic_userlist 133 and LM_A_CHECKOUT_DATA 178 lc_username 297 Ic_vsend 134 and ls_vendor_msg 233 lenient licensing 199 libemt lib MT 103 license count 42 license example expiring demo 26 floating counted 27 mixed counted and uncounted 28 node locked uncounted 26 PACKAGE 54 PACKAGE SUITE variations 57 PACKAGE SUITE_RESERVED variations 61 license file combining from multiple vendors 248 comment lines 32 decimal format 61 decimal format limits 273 definition 20 FEATURE line 36 FEATURESET line 195 format 23 INCREMENT line 36 limits 272 line continuation 32 PACKAGE line 52 SERVER line 33 UPGRADE line 50 USE_SERVER line 36 VENDOR line 35 license file setting HOME flexlmrc 98 140 Windows registry 98 140 license in a buffer 29 license job 126 license key 12 character 300 20 character 300 definition 20 length 299 length and start date 300 long 300 version behavior 301 license manager daemon 203 license manager daemon definition 21 license models expiring uncounted demo 197 lenient licensing 199 limited functionality demo 198 license policies LM_FAILSAFE 138 LM_LENIENT 138 LM_QUEUE 138 LM_RESTRICTIVE 137 license policy modifiers LM_CHECK_BADDATE 139 LM_FLEXLOCK 139 LM_MANUAL_HEARTBEAT 138 LM_RETRY_RESTRICTIVE 139 license server configuration 205 default ports 34 definition 20 improving performance 36 sockets used 274
105. Section 7 3 16 LM_A_RETRY_COUNT LM_A_RETRY_INTERVAL e Section 7 3 18 LM_A_USER_EXITCALL LM_A_USER_EXITCALL_EX S ection 7 3 19 LM_A_USER_RECONNECT LM_A_USER_RECONNECT_EX S ection 7 3 20 LM_A_USER_RECONNECT_DONE LM_A_USER_RECONNECT_DONE_EX FLEXIm Reference Manual August 2004 223 Manual Heartbeats 12 2 2 Manual Heartbeat Example 224 The code sequence below demonstrates one way to implement manual heartbeats it uses the FLEXible API This example incorporates the manual heartbeat timing loop within the main routine of the application with the intention that application code be included within this timing loop include Imclient h include lm_attr h VENDORCODE code LM_HANDLE 1lm_job int num_reconnects parameter to lc_heartbeat int num_minutes parameter to lc_heartbeat int hbstat return status for lc_heartbeat int exitcall char exit handler callback void main int argc char argv Initialize the job if lc_new_job 0 lc_new_job_arg2 amp code amp 1lm_job lc_perror lm_job lc_new_job failed exit lc_get_errno lm_job Turn off automatic heartbeat timing lc_set_attr lm_job LM_A_CHECK_INTERVAL LM_A_VAL_TYPE 1 lc_set_attr lm_job LM_A_RETRY_INTERVAL LM_A VAL TYPE 1 Set retry count to 3 default is 5 lc_heartbeat makes LM_A_RETRY_COUNT number of reconnection att
106. This handshake operation failed Clock difference too large between client and server The date on the client system does not agree closely enough with the date on the server daemon system The amount of difference allowed is set by the software vendor with Ic_set_attr LM_A_MAX_TIMEDIFF In the queue for this feature This checkout request has resulted in the process being placed in the queue for this feature Subsequent calls to Ic_status will yield the status of this queued request Feature database corrupted in daemon The daemon s run time feature data structures have become corrupted This 1s an internal daemon error User host on EXCLUDE list for feature The user host display has been excluded from this feature by an end user s vendor daemon options file User host not on INCLUDE list for feature The user host display has NOT been included in this feature by an end user s vendor daemon options file 282 FLEXIm Status Return Values 40 LM_CANTMALLOC 41 LM_NEVERCHECKOUT 42 LM_BADPARAM 43 LM_NOKEYDATA 44 LM_BADKEYDATA 45 LM_FUNCNOTAVAIL 47 LM_NOCLOCKCHECK Error Number Table Cannot allocate dynamic memory The malloc call failed to return sufficient memory Feature was never checked out This code is returned by Ic_status if the feature requested has never been checked out Invalid parameter A call
107. UITE_DUP_GROUP NONE SITE Optional field Similar to DUP_GROUP but affects only the enabling FEATURE line for a package suite UHDV If SUITE_DUP_GROUP is not specified the parent will have the same duplicate grouping as the components SUITE_DUP_GROUP limits the total number of users of the package to the number of licenses and allows the package to be shared among the users that have the SUITE checked out For example PACKAGE p COMPONENTS A B C OPTIONS SUITE FEATURE p 3 SUITE_DUP_GROUP UHD In this example SUITE_DUP_GROUP limits the number of component users to 3 and separately limits the number of uses of each component to 3 This keyword is valid only with counted licenses SEE ALso e Section 3 5 7 DUP_GROUP e Section 3 7 PACKAGE Lines SUPERSEDE SUPERSEDE featl featn Optional field Replaces existing lines in a license file Without the optional list of features allows vendors to sum up a set of INCREMENT lines in a single new FEATURE or INCREMENT line which supersedes all INCREMENT lines for the same feature name with previous START or ISSUED dates With the optional list of features it replaces all previously issued lines for feat 1 through featn Specifying the start date with the ISSUED keyword makes this date explicit e g ISSUED 1 jan 2005 If the ISSUED date is set then SUPERSEDE uses it otherwise it uses the START d
108. Uncounted License FEATURE 0 demo 2 0 permanent uncounted HOSTID 1234 SIGN AB0CCOC16807 Number of Licenses Version Feature Name Expiration Date Hostid Signature Keyword Vendor Daemon e Uncounted licenses have unlimited use on the hostid specified Uncounted licenses require no server e When the expiration date is permanent or if a date is specified with a year of 0 the license never expires e This license supports versions 0 0 through 2 0 inclusive 2 3 2 Expiring Demo License FEATURE f0 demo 2 0 3 mar 2005 uncounted HOSTID DEMO SIGN ABO0CCOC16807 Expiration Date 26 The License File Overview Types of License Files This license expires on 3 March 2005 Specify the year with four digits e g 1 jan 2001 The DEMO hostid indicates that this license allows f0 to run on any system In addition the client application can also detect that it is in demo mode and could behave differently 2 3 3 Simple Floating Counted License SERVER pat 17003456 2837 VENDOR demo E EATURE f1 demo 2 0 permanent 9 SIGN DBCC10416777 SERVER and VENDOR lines required Unexpiring Floating runs on any node No hostid on FEATURE line Limited to nine concurrent licenses Server restricted to hostid 17003456 To remove this restriction use hostid of ANY e g SERVER pat ANY 2837 A specific TCP IP port is specified 2837 for the license server connection
109. Use of a Vendor Defined Hostid Type 0 2 e eee ee Chapter 16 Debugging Hints 0 eee ee eee 16 1 Debugging Your Application Code 16 2 Solving Problems In The Field 0000 0 16 3 Multiple Vendors Using FLEX m at a Single End User Site 16 4 FLEX m Version Compatibility 000 0 Chapter 17 UNIX Platform Specific Notes 0 000000 0005 LTL Macintosh OSX 5 A oo ang aN ab TZ SSOLAS ud tada 17 3 Hewlett Packard eese irn E ad E TTB A A E be FAS Tem a il a ici O ISO a a a taa AO A E E Chapter 18 Windows Platform Specific Notes 0 000202 eee 18 1 Supported C Compilers 0 00 cee eee eee o 18 2 Using Languages Other Than C 0 0 00 0 18 3 Linking to your Program 1 2 eee eee eee 18 4 Windows Terminal Server Support 004 18 5 FLEX m Callback Routines 0 0 00 ee eee eee 18 6 FLEXIm exit Callback 0 0 0 0 cen 18 7 FLEXid Hardware Hostids Dongles o ooo 18 8 FLEX m Environment Variables 00000 18 9 Installing Imgrd as a Service Using installs Appendix A Industry Standard Licensing APIs 000002 e ee A 1 The FLEX m Trivial and Simple APIs A 2 The FLEX m FLEXible API 2 0 0 0 0 0 eee eee eee A3 SAPD VIG1 cierra raid FLEXIm Reference Manua
110. VAL TYPE 1 lc_perror job Note that this only works if another FLEX m error doesn t occur in between which would change the error condition and message Not all error conditions have long explanations or context sensitive information Example Invalid host The hostid of this system does not match the hostid specified in the license fil Hostid 12345678 License path filel lic file2 lic file3 lic FLEX1lm error 9 9 The format is short error description optional long explanation 1 3 lines optional context information License path pathl pathn FLEX1m error major minor Controlling Licensing Behavior FLEXible API Attributes set by Ic_set_attr 7 3 14 LM_A_PERROR_MSGBOX Windows Only Type int Default True If True Ic_perror presents the error message in an error dialog Also turned off when FLEXLM_BATCH is set 7 3 15 LM_A_PROMPT_FOR FILE Windows Only Type int Default True When True the user is prompted for the license file path or server name or IP address if needed Also turned off when FLEXLM_BATCH is set 7 3 16 LM_A_RETRY_COUNT LM_A_RETRY_INTERVAL Type int Default 5 for LM_A _ RETRY COUNT 60 for LM_A_RETRY_INTERVAL Together LM_A_RETRY_COUNT and LM_A_RETRY_INTERVAL are used for automatic reconnection to a license server Once license server failure 1s detected the automatic heartbeat mechanism attempts to reconnect to the license server
111. VERRIDE Note Type char Default No override of user name This string if specified will be used to override the user name as derived from the UNIX password file On Windows the user name is set to the host name but can be overridden with this attribute This value cannot be changed after the initial connection to the vendor daemon 8 2 17 LM_A_VENDOR_CALLBACK_DATA 186 Type void Default void NULL This attribute allows you to set a pointer to vendor defined data The pointer is of type void regardless of the data type This pointer is passed as the last argument to the following callback functions thus making this data available to those functions e LMA CHECKOUTFILTER_EX IM A USER_EXITCALL_EX LMA USER_RECONNECT_EX e LM A USER_RECONNECT_DONE_EX Advanced FLEXible API Features 8 3 Advanced Vendor Variables Advanced Vendor Variables The vendor variables in this section provide advanced capabilities beyond what is provided by the basic variables in Chapter 13 Vendor Daemon Table 8 3 Advanced Vendor Variables Variable ls_borrow_in Description Callback that removes the given borrow data record from a borrow data cache ls_borrow_init Callback that returns all borrow data records from a borrow data cache ls_borrow_out Callback that adds the given borrow data record to a borrow dat
112. X stderr WINDOWS dialog box SEE ALSO Section 4 2 4 It_heartbeat HEARTBEAT Section 5 2 4 Ip_heartbeat Section 6 4 12 Ic_heartbeat Section 7 2 1 LM_MANUAL_HEARTBEAT 12 2 1 Controlling Manual Heartbeat Behavior 222 Various aspects of manual heartbeat default behavior can be overridden by setting the appropriate FLEXible API attributes via Ic_set_attr Table 12 3 lists the attributes and the effect they have on automatic heartbeat behavior Heartbeats Table 12 3 Manual Heartbeat Control Manual Heartbeats Attribute Description Recomnection Strategy LM_A RETRY_COUNT Used to adjust the number of consecutive reconnect attempts each call to the heartbeat routine makes one attempt to a lost license server before the heartbeat routine causes the application to exit If 1 exit is never called Default is 5 attempts LM_A USER_RECONNEC LM_A USER_RECONNECT_EX Sets a pre reconnection callback to a vendor defined routine Default is no handler LM_A USER_RECONNECT_DONE LM_A USER_RECONNECT_DONE_E Sets a post reconnection callback to a vendor defined routine Default is no handler Lost Server Recovery LM_A USER_EXITCALL LM_A USER_EXITCALL_ EX Sets a callback to a vendor defined exit handler Default is for application exit SEE ALSO e
113. X include lm_attr h status lc_set_attr job attr LM_A_VAL_TYPE value DESCRIPTION Sets a FLEX m attribute attr describes which attribute to set and the value is the value for the attribute See the header file 1Im_attr h for attr constants and value types PARAMETERS LM_HANDLE job From Ic_new_job int attr Which attribute to set LM_A_VAL TYPE value Value to set it to Values should be of the appropriate type for the particular attribute see 1m_attr h but should be cast to LM_A_VAL_ TYPE RETURN int status 0 OK 0 error ERROR RETURNS LM_FUNCNOTAVAIL Vendor keys do not support this function LM_BADPARAM Specified parameter is incorrect LM_NOCONFFILE Specified license file cannot be found LM_A_LICENSE_FILE or LM_A_LICENSE_FILE_PTR 130 FLEXible API 6 4 21 FLEXible API Function Descriptions LM_NOSUCHATTR Specified attribute does not exist SEE ALso e Section 7 3 FLEXible API Attributes set by lc_set_attr Ic_status SYNTAX status lc_status job feature DESCRIPTION Returns the status of the requested feature A call to this function is made when QUEUEing for a license Normally QUEUEing is done in the following manner status lc_checkout LM_CO_NOWAIT if status LM _MAXUSERS status LM_USERSQUEUED printf Waiting for license status l1lc_checkout LM_CO WAIT However in the above e
114. XAMPLES VENDOR acmed VENDOR acmed etc acmed VENDOR acmed etc acmed options usr local licenses acmed opts WINDOWS EXAMPLES VENDOR acmed C Windows system acmed exe VENDOR acmed C Windows system acmed exe options C licenses acmed opts USE_SERVER Line USE_SERVER USE_SERVER takes no arguments and has no impact on the server When the client application sees a USE_SERVER line it ignores everything in the license file except the preceding SERVER lines In effect USE_SERVER forces the application to behave as though LM_LICENSE_FILE were set to port host or host USE_SERVER is recommended because it improves performance when a license server is used The advantages to USE_SERVER are that the application s license file e Does not need to match the one the server uses e Requires only SERVER and USE_SERVER lines FEATURE INCREMENT Lines FEATURE INCREMENT feature vendor feat_version exp_date num_lic vendor_keywords user_keywords SIGN sign A feature line describes the license to use with a FLEX m enabled product It is composed of five parts FEATURE or INCREMENT required e Positional fields required e Vendor keywords optional e User keywords optional e Signature required The License File Syntax FEATURE INCREMENT Lines The optional keywords must appear after all positional fields but can appear in any order User k
115. _MAXLIMIT 88 LM_BADSYSDATI E 89 LM_PLATNOTLIC 90 LM_FUTURE_FILE Error Number Table Incorrect number of USERS HOSTS INCLUDED in options file see server log When a feature has the USER_BASED attribute this error occurs when there no INCLUDE line in the end user options file for this feature or the number of users included exceeds the number authorized See Section 3 5 FEATURE INCREMENT Lines especially USER_BASED Server doesn t support this request This occurs when a vendor daemon with a FLEX m version older than the client is being used The daemon didn t understand and respond to the request made by the application Checkout exceeds MAX specified in options file End user option MAX has been specified for this feature System clock has been set back Returned from checkout call This platform not authorized by license Returned from checkout call where FEATURE line specifies PLATFORMS Future licens fil format or misspelling in license file Returned from checkout call when license file attribute was introduced in a later FLEX m version than the client FLEXIm Reference Manual August 2004 289 Error Number Table 91 LM_DEFAULT_SEEDS 9 2 LM_SERVER_REMOVED 93 LM_POOL 94 LM_LGEN_VER 95 LM_NOT_THIS_HOST LM_SEEDs are non unique Returned from Ic_new_job or
116. _RESERVED package component is checked out all the other components are reserved for that same user See Section 3 8 Decimal Format Licenses for more details SUPERSEDE Optional field but if used use with ISSUED date p1 p2 Replaces all PACKAGE lines for the same pr package name with ISSUED dates prior to dd ISSUED Optional field but if used use with SUPERSEDE dd mmm yyyy Replaces all PACKAGE lines for the same package name with ISSUED dates prior to date The purpose of the PACKAGE line is to support different licensing needs 1 To provide a way of distributing one line for a license file that has a large number of features which largely share the same FEATURE line arguments 2 To license a product suite A PACKAGE line by itself does not license anything it requires a corresponding FEATURE INCREMENT line to license the whole package A PACKAGE line can be shipped with a product independent of any licenses Later you can issue one or more corresponding FEATURE INCREMENT lines that will enable the package PACKAGE lines can be kept in a separate license file The path to the package file should be specified in the application to support this transparently via LM_A_LICENSE_DEFAULT FLEXIm Reference Manual August 2004 53 PACKAGE Lines 3 7 1 3 7 2 54 PACKAGE Example PACKAGE pkg demo 1 0 COMPONENTS c1 c2 c3 c4 c5 c6 c7 SIGN 504091605DCF FEATURE pkg demo 1 0 permanent
117. _RESTRICTIVE LM_MANUAL_HEARTBEAT This indicates that the main policy is LM_RESTRICTIVE that automatic heartbeats to the license server are disabled and that the application will call It_heartbeat HEARTBEAT or lp_heartbeat directly SEE ALSO e Section 12 1 Automatic Heartbeats LM_RETRY_RESTRICTIVE If this policy modifier is set the application will exit with a short error message after five failed heartbeat messages This is not normally recommended but is useful for some simple applications LM_CHECK_BADDATE If set attempts are made to detect whether the user has set the system date back This should be used in conjunction with setting 1s_a_check_baddate to 1 in the machind 1svendor c file SEE ALSO e Section 9 1 2 Limited Functionality Demos e Section 13 2 2 Is_a_check_baddate LM_FLEXLOCK If set FLEX ock functionality is enabled SEE ALSO e Information on FLEX ock in the FLEXIm Programmers Guide FLEXible API Attributes set by Ic_set_attr FLEXible API attributes allow you control over licensing policy internal operations of FLEX m e g automatic heartbeat mechanism etc and control of the licensing parameters of your process e g define how FLEX m will define username hostname and display name etc for managed license distribution To set FLEXible API attributes call the Ic_set_attr function described in Section 6 4 20 Ic_set_a
118. _SETITIMER LM_A_SIGNAL UNIX Only Controls which function is used in place of settimer LM_A_USE_START_DATE Enforces start date to be used in check outs See e Section 3 5 19 START 298 Obsolete FLEXible API Features D 3 D 4 D 4 1 Obsolete Vendor Daemon Variables Obsolete Vendor Daemon Variables The following vendor daemon variables are obsolete and exist only for compatibility with earlier FLEX m versions They should be used with care and questions are welcomed before their use Variable Description ls_a_lkey_long Enables 64 bit license keys License keys are obsolete See e Section 3 5 17 SIGN ls_a_lkey_start_date Enables embedded start dates in license keys License keys are obsolete See e Section 3 5 19 START ls_enforce_startdate Enforces start date to be used in check outs See e Section 3 5 19 START ls_tell_startdate Compares start date with system date See e Section 13 2 2 Is_a_check_baddate 1ls_use_featset Enables requirement of FEATURESET line FEATURESET is obsolete Obsolete License File Features License Key Length and Start Date This section applies only to licenses generated with license keys rather than signatures SIGN keywords The license key is the set of hex digits which appear on FEATURE INCREMENT UPGRADE PACKAGE lines and authenticates the text making the line secure
119. _perror e machind lmclient h 166 Advanced FLEXible API Features 8 1 9 Advanced FLEXible API Functions Ic_init_simple_composite SYNTAX status lc_init_simple_composite job hostid_list num ids DESCRIPTION This function initializes a vendor defined composite hostid Invoke this function right after the call to Ic_new_job The composite hostid is valid for the life of the license job and is accessed by specifying the HOSTID_COMPOSITE hostid type to Ic_hostid A composite hostid is a 12 byte hashed hexidecimal value formed by combining the values of one or more simple hostids types as specified by hostid_list Ifan invalid hostid type for the platform appears in hostid_list lc_init_simple_composite returns the value of the default hostid type for that platform EXAMPLE The following example demonstrates the definition and use of a composite hostid made up from HOSTID_ETHER and HOSTID_DISPLAY include lmclient h LM_HANDLE job char buf MAX_CONFIG_LINE Set up the list of hostid types which comprise the composite hostid hostids must appear in the same order as those in hostid lists specified in other components ay int hostid_list HOSTID_ETHER HOSTID_DISPLAY int num_ids 2 PR ee BY lc_new_job amp job Register the composite hostid ret lc_init_simple_composite job hostid list num_ids if ret 0 error processing PE A Now access
120. _sensitive 0 like LM_A_LICENSE_CASE_SENSITIVE If set to 1 licenses are case sensitive Default is 0 not case sensitive SEE ALSO e Section 8 2 10 LM_A_ LICENSE CASE SENSITIVE 13 2 4 Is compare _vendor_on_increment and Is Compare_vendor_on_upgrade int ls_compare_vendor_on_increment 0 Compare vendor defined int ls_compare_vendor_on_upgrade 0 Compare vendor def fields If VENDOR_STRING is used in your license files then the value of these two variables may need to be modified If one is set set both ls_compare_vendor_on_increment gives you control over whether an INCREMENT line will require the vendor string to match in order to pool its licenses If set to a non zero value then the string is included in the pooling decision if 0 then the string is not involved in pooling 228 Vendor Daemon 13 2 5 13 2 6 Vendor Variables 1ls_compare_vendor_on_upgrade gives you control over whether an UPGRADE line will require the vendor string to match in order to upgrade another license If set to a non zero value then the string is included in UPGRADE line matching decision if 0 then it is not included INCREMENT lines add licenses to a prior FEATURE or INCREMENT line and are combined into one pool if the all of the following is true e The feature names match e The feature versions match e Any node locked hostid if present matches USER_BASED and HOST_BASED field
121. _u3 directory edit the makefile from DAEMON demo replacing demo with your vendor daemon name Then type make in the sco_u3 directory FLEXIm Reference Manual August 2004 255 SCO 256 UNIX Platform Specific Notes Windows Platform Specific Notes FLEX m supports the Windows platforms using two sets of libraries Imgr lib and Imgr9a d11 18 1 Supported C Compilers The FLEX m client library on Windows is implemented as a static library or a DLL The DLL can interface with almost any compiler but is less secure However to build the FLEX m SDK including your vendor daemon on a Windows system FLEX m supports only the Microsoft Visual C compiler 5 0 or greater 18 2 Using Languages Other Than C FLEX m provides a function based API that is designed for non C languages such as Visual Basic See Chapter 4 Trivial API for more information 18 3 Linking to your Program FLEX m can be linked into your application in three ways e Linking statically with a FLEX m library that was built with the static C Runtime Library recommended The static FLEX m library is compiled with Microsoft Visual C 5 0 32 bit with multithreading enabled static C Runtime Library MT The static library is named lmgr 1lib FLEXIm Reference Manual August 2004 257 Windows Terminal Server Support 18 4 258 e Linking statically with a FLEX m library that uses the C Runtime Library as a
122. a cache 1s_borrow_return_early Controls ability for borrowed licenses to be returned early 1s_conn_timeout Controls vendor daemon connection timeout 1ls_do_checkroot Only UNIX Controls requirement for the vendor daemon s residence on a real root filesystem 1s_dump_send_data Controls the output of transmitted daemon data 1ve 1s_hud_hostid_case_sensit Controls case sensitivity for hostid types HOSTNAME DISPLAY and USER 1ls_use_all feature _ lines Controls feature line succession ls_user_lockfile Renames the vendor daemon locking mechanism only ls_user_lock Windows Renames the vendor daemon locking mechanism FLEXIm Reference Manual August 2004 187 Advanced Vendor Variables 8 3 1 Note 8 3 2 188 Is_borrow_in void 1s_borrow_in char borrowdata int datasize default_BorrowlIn This callback function removes the record that matches borrowdata from the borrow data cache The license server calls this function if set every time a borrow lingered license expires or a borrowed license is returned By default this callback is defined with an internal implementation that uses a predefined borrow data cache You can override the internal implementation with your own function that accesses your vendor defined cache Your implementation needs to e Open your vendor defined cache e Iterate through each record
123. achine s hostid Case 1 Users can run application A on the terminal server machine by sitting at the terminal server machine whether or not the feature line contains the TS_OK keyword The license is checked out as though it was a regular node locked license Case 2 If the feature line does not contain the TS_OK keyword and a user tries to run application A from a Terminal Server Client window an error is generated License fails to checkout 103 Windows Platform Specific Notes 18 5 18 6 18 7 FLEXIm Callback Routines Case 3 If the feature line contains the TS_OK keyword and one or more users try to run application A from a Terminal Server Client window the license is checked out and the application can run Ifthe feature line contains the TS_OK keyword FLEX m does not provide a way to limit the number of clients that can use this node locked license Counted licenses behave on a Terminal Server Client as they do on any other machines on a network FLEX m Callback Routines The FLEX m API supports application callbacks on various events such as lost of license and hostid acquisition Like all Windows SDK standard callback routines FLEX m application callback routines need special attention depending upon the environment that you are using The following code segments from the sample program demonstrates how this should be done void LM_CALLBACK_TYPE Quit char feature FLEX m exit Callback The default o
124. acro based Trivial API example program to demonstrate more advanced options The Imcrypt and makekey programs can be used to generate licenses for your customers or they can be used as examples of license generation programs Source to the Imcrypt and makekey programs is in the machind directory The Imcrypt and makekey programs generate the same signatures on all FLEX m supported platforms for all FLEX m versions thus allowing you to create licenses for any supported platform on any other supported platform FLEXIm Reference Manual August 2004 207 Lingering Licenses 11 2 11 3 208 FLEX m SDKs also contain an examples directory at the top level of the SDK hierarchy The examples directory contains example programs which have been put in the SDK to illustrate how to perform various operations with FLEXI m These programs are not supported and Macrovision may not include them in future FLEX m releases Lingering Licenses A lingering license allows you to specify how long a license will remain checked out beyond either the call to Ic_checkin or program exit whichever comes first To use this feature call lc_set_attr before checking out the feature that should linger lc_set_attr job LM_A_LINGER LM_A_VAL_TYPE x where x is the number of seconds to make the license linger In addition the end user can specify a longer linger interval in the vendor daemon s options file as such LINGER f1 100 Th
125. am e A part of a program e A piece of data restricted via the access functions A line in a license file that licenses a particular feature A feature line begins with one of the keywords FEATURE UPGRADE PACKAGE or INCREMENT FLEXIm Reference Manual August 2004 19 FLEXIm Terms and Definitions Floating license Heartbeats License License file License file list License key License server 20 Introduction A license that can authorize usage of an application by one of a group of users on a network A license server is required to manage a floating license Floating licenses must be counted Periodic messages sent from a client application to a license server to solicit replies that ensure that the license server is still running Heartbeats can be implemented automatically or called explicitly from a client application If called explicitly they are referred to as manual heartbeats The legal right to use a feature FLEX m can restrict licenses for features by counting the number of licenses already in use for a feature when new requests are made by the client application software FLEX m can also restrict software usage to particular nodes or user names A text file specific to an end user site that contains descriptions of 1 license server node s 2 vendor daemons and 3 licenses features for all supported products 66 99 A list of license files separated with a colon on UNIX and a
126. and job creation because it offers enhanced security PARAMETERS LM_HANDLE job Must be NULL on first call to Ic_init Otherwise the current job on all subsequent calls char vendor_id Vendor name as defined with VENDOR_NAME in machind 1m_code h pointer to From LM_CODE macro VENDORCODE code 124 FLEXible API RETURN pointer to LM_HANDLE Ilm job ER L L L L L L L E L L L SE e Section 6 4 4 lc_cryptstrQ int status ROR RETURNS M_BAD_TZ M_BADPLATFORM M_BADKEYDATA M_BADVENDORDATA M_CANTMALLOC M_DEFAULT_SEEDS M_EXPIRED_KEYS M_NOKEYDATA M_LIBRARYMISMATCH M_NONETWORK M_OLDVENDORDATA E ALSO FLEXible API Function Descriptions Set to job for the current process This is used as the first argument to all subsequent Ic_xxx functions Value of Ic_get_errno after initialization is complete 0 if successful Time zone offset from GMT is gt 24 hours may imply a user is attempting to bypass an expiration date Vendor keys do not support this platform Bad vendor keys Unknown vendor key type The call to malloc failed Encryption seeds were left to default values but the vendor daemon name is not demo Vendor keys have expired Vendor key data not supplied Imclient h liblmgr a version mismatch Networking software not available on this machine Old vendor keys supplied e Section 6 4 17
127. and Ic_convert 163 and lc_expire_days 110 and lc_free_hostid 164 and Ic_free_job 113 and Ic_remove 171 and lc_set_attr 130 LM_BADPKG 82 288 LM_BADPLATFORM 48 284 and Ic_init 125 and Ic_new_job 127 LM_BADSYSDATE 88 289 and Ic_checkout 99 LM_BADVENDORDATA 65 286 and Ic_init 125 and Ic_new_job 127 LM_BORROW_DELETE_ERR 122 293 LM_BORROW_DOWN 120 293 LM_BORROW_ERROR 102 and lc_borrow_return 160 LM_BORROW_EXPIRED 118 293 LM_BORROW_LINGER_ERR 117 293 LM_BORROW_MATCH_ERR 128 294 LM_BORROW_RETURN_EARLY_ E RR 123 293 LM_BORROW_RETURN_SERVER_E RR 124 293 and Ic_borrow_return 160 LM_BORROW_TOOLONG 104 292 and Ic_checkout 99 LM_BORROWLOCKED 70 277 LM_BUSYNEWSERV 23 281 and Ic_checkout 99 LM_CANT_CHECKOUT_JUST_PAC KAGE 125 294 FLEXIm Reference Manual August 2004 311 LM_CANT_DECIMAL 98 291 LM_CANTCOMPUTEFEATSET 56 285 LM_CANTCONNECT 15 279 and Ic_borrow_return 160 and Ic_checkout 99 and Ic_remove 171 and Ic_status 132 LM_CANTFINDETHER 29 281 LM_CANTMALLOC 40 283 and 1_new_hostid 158 and Ic_feat_list 111 and Ic_init 125 and Ic_new_job 127 and Ic_userlist 134 LM_CANTREAD 16 280 and Ic_remove 171 and Ic_shutdown 172 and Ic_vsend 135 LM_CANTWRITE 17 280 and Ic_borrow_return 160 and Ic_log 126 and Ic_remove 171 LM_CHECK_BADDATE 139 LM_CHECKINBAD 22 280 LM_CHECKOUTFI
128. anted iser ut Note that both available sets of package components are reserved for user u1 by virtue of that user initially being granted two identical component licenses In the example depicted above user u1 gets both of the grants for write thereby reserving the rest of the components from both available packages for him This paradigm shuts out user u2 from any of the licenses in the package DUPLICATE GROUPING CONSIDERATIONS When OPTIONS SUITE_RESERVED is specified in the PACKAGE line set DUP_GROUP NONE in the component FEATURE lines Specifying DUP_GROUP with any other setting masks the reserved feature and the behavior is as if OPTIONS SUITE had been specified in the PACKAGE line Consider the following license file with DUP_GROUP set PACKAGE office demo 1 0 COMPONENTS write paint draw OPTIONS SUITE_RESERVED SIGN 00504091605D FEATURE office demo 1 0 permanent 2 SUITE_DUP_GROUP U DUP_GROUP U SIGN DB5CC00101A7 This variation has the same behavior as in A Fixed Number of Users with Unlimited Component Usage below SEE ALSO e Section 7 3 10 LM _A LICENSE DEFAULT PACKAGE SUITE Example A package suite provides more flexibility in the way floating licenses are used than just granting a license that applies to one feature Within a package suite a floating license is shared among the component of the package rather than being applied to one specifi
129. application s detection of license server failures LM_A_RETRY_COUNT LM_A_RETRY_INTERVAL Specifies the number of and the interval between automatic reconnection attempts LM_A_TCP_TIMEOUT Specifies amount of time to wait after TCP disconnection before license is automatically checked in LM_A_USER_EXITCALL LM_A_USER_EXITCALL_EX Pointer to a function that receives control if reconnection fails LM_A_USER_ RECONNECT LM_A_USER_RECONNECT_EX Pointer to a function that is called just before a reconnection attempt LM_A_USER_RECONNECT_DONE LM_A_USER_RECONNECT_DONE _EX Pointer to a function that is called after a successful reconnection FLEXIm Reference Manual August 2004 85 FLEXible API Functions by Category 6 2 4 Informational Table 6 5 lists the informational functions and attributes They provide status and usage information not critical to the license management process Table 6 5 Informational Function or Attribute Name Description Functions Ic_expire_days Returns the number of days until a license expires Ic_feat_list Gets the list of all features in the license file Ic_log Logs a message in the debug log file Ic_userlist Provides a list of who is using a feature Helpful to explain why a license is denied Ic_vsend Sends a message to the vendor daemon and returns a result string Attributes LM_A_BORROW_ST
130. apter 4 Trivial APT and Chapter 5 Simple API respectively There is however no reason to change APIs in applications which already use the FLEXible API Some FLEX m functionality is available only in this API For example the C interface to license generation Ic_cryptstr is available only in the FLEXible API 6 1 FLEXible API Function Summary This section lists the popularly used FLEXible API functions Full descriptions for them are found later in this chapter For a grouping by function category see Section 6 2 FLEXible API Functions by Category Programming examples using the FLEXible API and instructions for building your licensed application are located in the FLEXIm Programmers Guide Table 6 1 FLEXible API Function Summary Function Name Ic_auth_data Description Gets the license file line for a checked out feature Ic_checkin Returns a license of a feature to the license pool Ic_checkout Requests a license of a feature Ic_cryptstr Generates a valid signature in a feature line Ic_err_info Returns error information to an LM_ERR_INFO structure pointer FLEXIm Reference Manual August 2004 81 FLEXible API Function Summary 82 Table 6 1 FLEXible API Function Summary Continued Function Name Description Ic_errstring Returns the FLEX m error string for the most recent FLEX m error Ic_expire_days Returns the
131. are building a DLL and the FLEX m library 1mgr 11b is linked into your DLL Or put another way the FLEX m functions are not in a static binary but only in a DLL In this case the DLL makes calls to the following functions before calling Ic_checkout lc_set_attr job LM_A_WINDOWS_MODULE_HANDLE LM_A_VAL TYPE GetModuleHandle d11name where d11nameis the name of the DLL If these calls are not made Windows dialogs and error messages do not work properly FLEXIm Reference Manual August 2004 155 FLEXible API Attributes set by Ic_set_attr 156 Controlling Licensing Behavior Advanced FLEXible API Features The FLEXible API functions attributes and vendor variables in this chapter provide advanced FLEX m functionality Basic functionality is covered by the material in Chapter 6 FLEXible API Chapter 7 Controlling Licensing Behavior and Chapter 13 Vendor Daemon 8 1 Advanced FLEXible API Functions The following FLEXible API functions are advanced and used for functionality not found in the basic set of functions They should be used with care and questions are welcomed before their use Table 8 1 summarized these functions Table 8 1 Advanced FLEXible API Functions Function _new_hostid Description Allocates a hostid structure Ic_borrow_return Returns a borrowed license early Ic_check_key Validates a license signature Ic_cleanup
132. at current feature is noted in the tables below If you are implementing FLEX m for the first time into your application refer to reference material elsewhere in this manual e Chapter 6 FLEXible APT e Chapter 7 Controlling Licensing Behavior e Chapter 8 Advanced FLEXible API Features e Chapter 13 Vendor Daemon D 1 Obsolete FLEXible API Functions The following functions are obsolete and exist only for compatibility with earlier FLEX m versions They should be used with care and questions are welcomed before their use Function Ic_alarm Description Sets a timer See e Section 6 4 12 Ic_heartbeat e Section 7 3 5 LM_A_CHECK_INTERVAL Ic_baddate Detects if system date has been set back See e Section 7 3 4 LM_A_CHECK_BADDATE e Section 13 2 2 Is_a_check_baddate FLEXIm Reference Manual August 2004 295 Obsolete FLEXible API Functions 296 Function Ic_chk_conf Description Validates a config structure See e Section 6 4 1 Ic_auth_data Ic_ck_feats Checks the FEATURESET line for a given vendor FEATURESET is no longer used Ic_copy_hostid Returns a copy of the hostid list See e Section 6 4 13 Ic_hostid Ic_crypt Computes the license key for a FEATURE line See e Section 6 4 4 lc_cryptstrQ Ic_disalarm Turns off a timer set with lc_alarm See
133. at users will not timeout applications that are in use If the license is inadvertently released the next Ic_heartbeat will automatically re acquire the license if there is still a license available SEE ALSO e Chapter 12 Heartbeats e Section 7 3 5 LM_A_CHECK_INTERVAL e Section 7 3 16 LM_A_RETRY_COUNT LM_A_RETRY_INTERVAL e Section 7 3 17 LM_A_TCP_TIMEOUT e Section 7 3 18 LM_A_USER_EXITCALL LM_A_USER_EXITCALL_EX e Section 7 3 19 LM_A_USER_RECONNECT LM_A_USER_RECONNECT_EX e Section 7 3 20 LM_A_USER_RECONNECT_DONE LM_A_USER_RECONNECT_DONE_EX e Section 13 2 9 Is_minimum_user_timeout e TIMEOUT options file keyword in the FLEXIm End Users Guide 6 4 13 Ic_hostid 118 SYNTAX char buf MAX_CONFIG_LINE status lc_hostid job id_type buf DESCRIPTION Fills in buf with a hostid string specified by id_type If id_type is HOSTID_DEFAULT you get the default id_type on the system FLEXible API FLEXible API Function Descriptions This function allows developers access to hostid information in string format Note that Ic_hostid may return a space separated list of hostids if appropriate If a request is made for an invalid hostid type for a platform Ic_hostid returns the value of the default hostid type for that platform If a request is made for a valid type that is not currently present on the machine such as HOSTID_FLEXID6 on Windows Ic_ho
134. ate For example FLEXIm Reference Manual August 2004 47 FEATURE INCREMENT Lines INCREMENT f1 1 ISSUED 1 jan 2005 INCREMENT fl 4 SUPERSEDE ISSUED 1 jan 2007 The second line supersedes the first and causes FLEX m to ignore the first line FEATURE fl 1 ISSUED 1 jan 2003 FEATURE f2 1 ISSUED 1 jan 2003 FEATURE f3 4 SUPERSEDE f1 2 ISSUED 2 jan 2003 f3 supersedes f1 and f2 and causes FLEX m to support only f3 Multiple INCREMENT lines for the same feature both specifying SUPERSEDE with the same ISSUED date will be pooled together rather than superseding one another The resulting license pool will collectively supersede the older feature For example INCREMENT fl 1 ISSUED 1 jan 2005 INCREMEN fl 4 SUPERSEDE ISSUED 1 3Jan 2007 INCREMENT f1 3 SUPERSEDE ISSUED 1 Jjan 2007 will result in a license pool containing 7 licenses for f1 collectively superseding the first INCREMENT line 3 5 22 TS_OK TS_OK Optional field FLEX m detects when a node locked uncounted license is running under Windows Terminal Server If you want to allow users to run on Terminal Server client machines the TS_OK keyword must be added to the feature line Without the TS_OK keyword a user running on a Terminal Server cli
135. authenticates a FEATURE INCREMENT line locally as being valid for fulfilling the license request This filter provides the application the opportunity to examine the FEATURE INCREMENT line after lc_checkout authenticates it locally and either allows lc_checkout to proceed processing the line or rejects this particular line If the filter function allows processing to proceed lc_checkout passes a served license request to the license server where it still may get denied The LM_A_CHECKOUTFILTER_EX routine is called as follows status myCheckoutFilterLastEx job config vendor_data Advanced FLEXible API Features Advanced FLEXible API Attributes CALLBACK PARAMETERS LM_HANDLE job A pointer to the license job that was passed to the call to Ic_checkout CONFIG config A pointer to the CONFIG struct representing the authenticated feature line void vendor_data A pointer to either vendor defined data set via the LM_A_VENDOR_CALLBACK_DATA attribute or NULL RETURN VALUES The return value from this function effects the outcome of the current checkout request in the following ways e Ifo is returned For served licenses lc_checkout passes the license request to the license server for further processing For unserved licenses lc_checkout checks out the license Ifa non zero value is returned Ic_checkout does not continue to evaluate the current FEATURE line but instead tak
136. bled application connected to a vendor daemon uses one or more sockets The number of sockets any one FLEX m enabled application requires is dependant on FLEX m implementation details each job handle consumes one socket The number of sockets available to the vendor daemon is defined by the per process system limit for file descriptors The total number of sockets used by the license server 1mgrd and the vendor daemon together is slightly larger than the total number needed by the FLEX m enabled applications When using UDP there is no limit to the number of applications per vendor daemon process because they can share a single socket in the vendor daemon FLEXIm Parameter Limits B 8 B 9 Imgrd Limits In practice we encourage end users to put servers on systems configured with enough file descriptors per process to support the number of FLEX m enabled applications connecting to the vendor daemon which may require reconfiguring the kernel to increase the number of file descriptors per process Note that multiple daemons can be run on a single network making the number of TCP clients effectively unlimited NUMBER OF VENDOR DAEMONS PER NODE A particular vendor daemon can only be run once per node This is a security mechanism to prevent extra licenses from being granted There is no limit to the number of different vendor daemons that can be run per node Imgrd Limits lmgrd processes per node Unlimited Default port number
137. but not have a checkout depend on the returned information call lc_auth_data after a successful checkout Because Ic_auth_data returns only features which have been successfully checked out the returned data is authenticated If you call lc_checkout with the LM_CO_LOCALTEST flag use the alternate function Ic_test_conf to retrieve the desired license file line instead of Ic_auth_data SEE ALso e machind lmflex c e Section 6 4 1 Ic_auth_data e Section 8 2 2 LM_A_CHECKOUT_DATA e Section 6 4 20 Ic_set_attr FLEXible API 6 4 4 FLEXible API Function Descriptions Section 8 2 3 LM_A_CHECKOUTFILTER LM_A_CHECKOUTFILTER_EX Section 8 2 4 LM_A_CHECKOUTFILTERLAST_EX Section 7 3 1 LM_A_APP_DISABLE_CACHE_READ Section 7 3 6 LM_A_CKOUT_INSTALL_LIC Section 7 3 10 LM_A_LICENSE_DEFAULT Section 8 2 9 LM_A_HOST_OVERRIDE Section 8 2 8 LM_A_ DISPLAY _OVERRIDE Section 8 2 16 LM_A_USER_OVERRIDE Section 6 4 2 Ic_checkin Section 3 5 FEATURE INCREMENT Lines e Section 6 4 21 Ic_status e Section 11 4 Multiple Jobs Ic_cryptstr SYNTAX status lc_cryptstr lmjob str return_str code flag filename errors DESCRIPTION Signs the given license certificate This function is used by license certificate generation utilities such as 1mcrypt and as such is not intended to be incorporated into your application
138. c feature Various license sharing scenarios are created within the package suite paradigm using feature and suite duplicate grouping The examples given below use the U user duplicate grouping criterion Other criteria H host D display and V vendor defined can be used to provide a finer FLEXIm Reference Manual August 2004 57 PACKAGE Lines granularity for the duplicate grouping specification More information regarding duplicate grouping is found in Section 3 5 7 DUP_GROUP and Section 3 5 20 SUITE_DUP_GROUP A FIXED NUMBER OF USERS WITH UNLIMITED COMPONENT USAGE In this variation licenses are granted to a fixed number of users at any one time Each user is granted an unlimited number of licenses for each suite component PACKAGE office demo 1 0 COMPONENTS write paint draw OPTIONS SUITE SIGN 00504091605D FEATURE office demo 1 0 permanent 2 SUITE_DUP_GROUP U DUP_GROUP U SIGN DB5CC00101A7 This license file defines a package suite named of fice with three components write paint and draw Additionally the suite and feature duplicate grouping criteria SUITE_DUP_GROUP U and DUP_GROUP U are defined to the user level At most two distinct users at any one time can be granted unlimited licenses This concept is illustrated in the following table oe Requested Checkout User q Result Explanation Feature Attempt 1 ul write paint unlimited Unlimited lice
139. c_heartbeat more frequent than 30 seconds are ignored That is a reconnection is attempted at most every 30 seconds even when Ic_heartbeat is called more frequently e The application can optionally define a pre reconnection callback function via the LM_A_USER_ RECONNECT attribute e Ifareconnection occurs before five attempts and the application defines a post reconnection callback function via the LM_A_USER_RECONNECT_DONE attribute it is called e Ifareconnection fails to occur after five attempts the a callback exit handler if specified with the LM_A_USER_EXITCALL attribute is called Otherwise the application exits with the error message Lost License cannot re connect UNIX stderr WINDOWS dialog box FLEXIm Reference Manual August 2004 117 FLEXible API Function Descriptions LC_HEARTBEAT AND USER TIMEOUT OPTION If Ic_heartbeat is not called for an extended period then the application may lose its license This can happen for two reasons the timeout set with the LM_A_TCP_TIMEOUT attribute has expired or the end user has set a TIMEOUT for this feature in the end user options file In both cases the license server has a timeout associated with the license which gets invoked if Ic_heartbeat is not called within the timeout interval Make sure that LM_A_TCP_TIMEOUT is large enough to accommodate your usage of Ic_heartbeat Similarly make sure 1s_minimum_user_timeout in lsvendor c is large enough so th
140. called on a healthy client the license will be checked out again by the client with its next heartbeat If Imgra is started with the x 1mremove flag then lc_remove has no effect PARAMETERS LM_HANDLE job From Ic_new_job char feature Remove the license for this feature char user User name of license to remove char host Host name of license to remove char display Display name of license to remove Advanced FLEXible API Features RETURN int status ERROR RETURNS M_BADCOMM M_BADPARAM M_CANTCONNECT M_CANTWRITE L L L LM_CANTREAD L LM_NOFEATURE L M_NOTLICADMIN LM_REMOVETOOSOON SEE ALso Advanced FLEXible API Functions 0 OK 0 error status Communications error No licenses issued to this user Cannot connect to license server Cannot read from license server Cannot write to license server Feature not found in license file data Failed because user is not in Imadmin group Failed because 1s_min_lmremove time has not elapsed e Chapter 10 The License Manager Daemon e Section 13 2 8 ls_min_Imremove e Section 6 4 12 Ic_heartbeat 8 1 12 Ic_shutdown SYNTAX status 1c_shutdown job prompt print DESCRIPTION Shuts down the FLEX m servers This is used by 1mdown FLEXIm Reference Manual August 2004 171 Advanced FLEXible API Functions PARAMETERS LM_HANDLE job From Ic_new_job int prompt Unused
141. cense file where the signatures are replaced with SIGN 0 pointer to Resulting license file string Malloc d by char return_str_ lc_cryptstr and freed by the calling program Pass the address of a char pointer pointer to From LM_CODE macro VENDORCODE code 104 FLEXible API FLEXible API Function Descriptions int flag Mask which can be binary OR d I with the following flags LM_CRYPT_ONLY TIf true only return signature for first FEATURE in str LM_CRYPT_FORCE TIf set recompute the signature for every line even if the signature is already present on the line LM_CRYPT_IGNORE_FEATNAME_ ERRS TIf set no warnings returned about invalid feature names LM_CRYPT_DECIMAL Output will be decimal format Otherwise readable format char filename For error reporting or char 0 This name will appear in the error message as the file name pointer to For error reporting or char 0 If char errors there are errors the return value is non zero and errors is set to an explanatory string Malloc d by Ic_cryptstr and freed by the calling program use Ic_free_mem on Windows Pass the address of a char pointer If a warning occurs errors is set toa warning string but the return value is 0 success RETURN int status 0 success 0 indicates an error occurred ERROR RETURNS Because different errors can occur on every line of the input str lc_cryptstr must be able to
142. cense server or otherwise does not contain a USE_SERVER line The following types of lines are found in this section FEATURE line Defines the individual licensed feature INCREMENT line Adds additional entitlement to an existing feature or increment line for the same feature UPGRADE line Upgrades entitlement for an existing feature See the FLEXIm Programmers Guide for information on 1Imcrypt and makekey the license generation utilities Also see Section 6 4 4 Ic_cryptstrQ for generating licenses with a C function call Vendors and license administrators read the license file to understand how the licensing behaves for example what features are licensed the number of licenses whether these features are node locked if the features are demo or regular etc The SERVER hostids and everything on a FEATURE line except the vendor daemon name and lowercase keyword value pairs are input to the authentication algorithm to generate the signature for that FEATURE line If the authenticated portions are edited an LM_BADCODE error will result when the FLEX m enabled product tries to checkout a license for that feature In summary the only data items in the license file that are editable by the end user are Host names on SERVER lines e Port numbers on the SERVER or VENDOR lines e Path names on VENDOR lines e Options file path names on VENDOR lines e Lowercase keyword value pairs on FEATURE lines The License File
143. cimal Licenses 005 62 3 8 3 Format of a Decimal License 0055 63 3 8 4 Hints on Using the Decimal Format 63 Chapter 4 TAa APP 6 0 08 6 0 iaa 65 4 1 Overview of the Trivial API oo ooooooooom o o 65 4 1 1 License Acquisition 0 0 0 cee eee ee eee eee 66 4 1 2 Heartbeat Management 0 00 2 eee 66 4 1 3 Error and Warning Processing 200 5 66 iv FLEXIm Reference Manual August 2004 4 2 Trivial API Descriptions 0 0 eee eee eee 67 4 2 1 It_checkinQ CHECKINO 0 0 0 0 e ee eee eee 67 4 2 2 It_checkout CHECKOUT 0 00000 000 67 42 3 lt_errstringO ERRSTRINGO 00020 e eee 69 4 2 4 lt_heartbeatO HEARTBEATQ 0 000008 69 4 2 5 lIt_perror PERRORO 0 ccc eee 70 42 6 It_pwarn PWARN 0 ee eee eae 70 4 2 7 It_warning WARNINGO 0 00 eee eee eee 71 Chapter 5 Simple APL gi feted de Maen oh ee edd shen essa stead Se ee 73 5 1 Overview of Simple API Functions 0004 73 5 1 1 Checkin and Checkout Functions 4 73 5 1 2 Heartbeat Function 2 0 74 5 1 3 Error and Warning Processing Functions 74 5 2 Simple API Function Descriptions 0005 74 52 6 Ipocheckin er i e cee eee oo Cae oe ies ale ees 74 52 2 IpscheckOut ici saad ales dates kata
144. ck the appropriate platform specific notes in Chapter 17 UNIX Platform Specific Notes or Chapter 18 Windows Platform Specific Notes e On UNIX the sleep 3 pclose 3 and system 3 calls often do not work with FLEX m s default use of SIGALRM If you must use these calls disable FLEX m automatic heartbeats by setting LM_A_CHECK_INTERVAL and LM_A_RETRY_INTERVAL to 1 with Ic_set_attr and call Ic_heartbeat periodically e On UNIX FLEX m installs a handler for SIGPIPE and SIGALRM If your application uses FLEX m automatic heartbeats and forks execs another process these signals must be restored to the default before the fork exec and then re restored in the parent process See signal 3 for details If you fail to do this the child process will fail with a segmentation violation since the signal handler will not exist in the child process This is due to the fact that the child inherits the signal handler setting of the timer but it does not inherit the signal handler code e Ifthe daemon log file is missing be sure that you are using Bourne shell syntax in the startup file In particular do not use csh style redirection gt in one of the rc startup files If the FLEX m timers are used to perform checking and or reconnection non reentrant routines can possibly be called in the C run time library We have verified that the routines called by the timers are free of malloc free re entrancy problems since these are det
145. d A complete sample application incorporating a composite hostid is located in examples composite lmcomplex c SEE ALSO e Section 6 4 13 Ic_hostidQ e Section 8 1 9 Ic_init_simple_composite Initializing a Composite Hostid in Your Vendor Daemon For served licenses your vendor daemon has to validate the hostid specified on the SERVER line with that retrieved from the machine on which the license server is running If a composite hostid is specified on the SERVER line then the vendor daemon must validate it Follow these steps to modify your vendor daemon with the code necessary for this validation 1 Open machind lsvendor c ina text editor 2 At the beginning of the vendor initialization routine section add a line defining init_composite_hostid and modify the initial value of ls_user_init1 from 0 to init_composite_hostid Vendor initialization routines void init_composite_hostid void ls_user_initl init_composite_hostid 3 Save and close machind lsvendor c 4 Open a new file init_composite c in a text editor FLEXIm Reference Manual August 2004 237 Initializing a Composite Hostid in Your Vendor Daemon 5 In init_composite c provide code similar to the following for init_composite_hostid include lmclient h Set up the list of hostid types which comprise the composite hostid hostids must appear in the same order as those in hostid lists specified in other components Rf
146. d HOSTID ANY VENDOR_STRING Acme Inc SIGN 50A35101C0F3 n END_LICENSE The license must begin with START_LICENSE n and end with nEND_LICENSE where the embedded newlines are required This can also be a license file list as in the following example CHECKOUT LM RESTRICTIVE ELE 1 0 nath_to_license_file START_LICENSE n P FEATURE f1 demo 1 0 permanent uncounted HOSTID ANY VENDOR_STRING Acme Inc SIGN 50A35101C0F3 n END LICENSE In this example path_to_license_fileis first in the list followed by the license in the string Specifying a license in a buffer is particularly useful when selling libraries if a separate license file is not desirable or as a final fail safe license in the event that the license server is not running FLEXIm Reference Manual August 2004 29 License in a Buffer 30 The License File Overview The License File Syntax This chapter is a reference for license file syntax It is divided up into sections which correspond to the different license file sections as outlined in Section 2 1 Format of the License File For an overview of license files see Chapter 2 The License File Overview Table 3 1 lists the license file sections described in this chapter Table 3 1 License File Sec tions Section General Syntax Issues Sy
147. d Ic_init 125 and Ic_new_job 128 LM_LICENSE_FILE and LM_A_DISABLE_ENV 182 and LM_A_LICENSE_DEFAULT 145 and Imgrd 205 and multiple jobs 209 limits 275 LM_LOCALFILTER 73 287 and Ic_checkout 99 LM_LONGGONE 10 278 and Ic_expire_days 110 LM_MANUAL_HEARTBEAT 138 LM_MAXLIMIT 87 289 and Ic_checkout 99 LM_MAXUSERS 4 277 and Ic_checkout 99 LM_MUST_BE_LOCAL 119 293 LM_NEVERCHECKOUT 41 283 and Ic_status 132 Im_new o 126 Im_new obj 126 LM_NO_SERVER_IN_FILE 13 279 and Ic_checkout 99 LM_NOADMINAPI 78 288 and lc_get_attr 115 and LM_A_VD_ _INFO 152 LM_NOBORROW_SUPP 68 and Ic_checkout 99 LM_NOBORROWSUPP 68 287 LM_NOCLOCKCHECK 47 283 LM_NOCONFFILE 1 277 and Ic_get_config 165 and lc_set_attr 130 LM_NOCROSUPPORT 116 293 LM_NODONGLE 110 292 LM_NODONGLEDRIVER 112 292 LM_NOFEATSET 54 284 LM_NOFEATURE 5 277 and Ic_auth_data 91 and Ic_borrow_return 160 and Ic_checkout 99 and Ic_feat_list 111 and Ic_get_config 165 and Ic_remove 171 and Ic_userlist 134 LM_NOFLEXLMINIT 51 284 LM_NOKEYDATA 43 283 and Ic_init 125 and Ic_new_job 128 Im_nomt o 251 LM_NONETOBORROW 67 286 LM_NONETWORK 62 286 nd lc_init 125 nd lc_new_job 128 LM_NOREADLIC 30 281 and Ic_get_config 165 LM_NOSERVCAP 85 289 LM_NOSERVER 3 277 LM_NOSERVICE 6 278 LM_NOSERVRESP 52 284 Ds 2 LM_NOSERVSUPP 18 280 and Ic_check
148. d send the reply This routine is specified in lsvendor c inthe variable 1s_vendor_msg PARAMETERS LM_HANDLE job From Ic_new_job char send_str String to be send to your vendor daemon FLEXible API FLEXible API Function Descriptions RETURN char rcv_str String returned by ls_vendor_msg in your vendor daemon 0 if unsuccessful ERROR RETURNS LM_BADCOMM Communications problem with the vendor daemon LM_CANTREAD Cannot read data from license server LM_NOSERVSUPP Your vendor daemon does not support this function SEE ALSO e Section 13 2 15 ls_vendor_msg FLEXIm Reference Manual August 2004 135 FLEXible API Function Descriptions 136 FLEXible API Controlling Licensing Behavior Licensing behavior is controlled from within the FLEX m licensed application by setting license policies and attributes The Trivial and Simple APIs provide a set of license policies and policy modifiers that are specified in the call to the checkout function The FLEXible API allows you to control the licensing behavior of your application by setting attributes with the lc_set_attr function The information in this chapter is divided into the following sections e Trivial and Simple API License Policies e Trivial and Simple API Policy Modifiers e FLEXible API Attributes set by lc_set_attr 7 1 Trivial and Simple API License Policies The Trivial and Simple APIs both require that you specify a license policy
149. d user to derive the composite hostid from their machine on which your product is installed e Issue licenses that specify the COMPOSITE hostid type The subsequent sections below explain each of these actions in detail SEE ALSO e Section 2 2 Hostids for FLEXIm Supported Machines e Section 3 2 SERVER Lines e Section 3 5 10 HOSTID FLEXIm Reference Manual August 2004 235 Defining a Composite Hostid 14 2 14 3 236 Defining a Composite Hostid A composite hostid is defined by a list of simple hostid types As few or as many types can be incorporated in the list as is appropriate for your license policy When FLEX m validates the machine s composite hostid it retrieves the values for each hostid type in the list combines them and applies a hashing algorithm to produce a 12 character hexidecimal value At license authentication time FLEX m compares the calculated value to that in the FEATURE or SERVER line an exact match indicating a legitimate machine for processing to proceed That means the value for each constituent in the composite hostid list must match exactly to that which is used in the original composite hostid calculation The more hostid types included in the composite hostid the tighter the tolerance is to accept the machine as a legitimate host Consult Section 6 4 13 Ic_hostid for a list of simple hostid types that can be included in a composite hostid The following sections i
150. data to obtain the CONFIG pointer after a successful checkout If the FEATURE line information needs to be authenticated before a checkout is done use Ic_checkout with the LM_CO_LOCALTEST flag then Ic_test_conf can be used to obtain the CONFIG pointer If data authentication is not needed Ic_next_conf can be used to get the CONFIG pointer RETURN int days LM_FOREVER Unexpiring license gt 0 Number of days until expiration 0 The license will expire tonight at midnight lt 0 FLEX m errno ERROR RETURNS LM_BADPARAM conf is 0 LM_LONGGONE The feature has already expired 110 FLEXible API 6 4 8 FLEXible API Function Descriptions SEE ALso e Section 6 4 3 Ic_checkout e Section 8 1 10 Ic_next_conf Ic_feat_list SYNTAX list lc_feat_list job flags dupaction DESCRIPTION Gets the list of all features in the license file PARAMETERS LM_HANDLE job From Ic_new_job int flags LM_FLIST_ALL_FILES for all license files If O only the first license in the license file list is used void dupaction Action routine called when a duplicate feature is found This routine is called upon the second occurrence of any feature name If specified as NULL no call is made RETURN char list List of features list is a pointer to a NULL terminated array of feature string pointers Both the pointers and the string data are malloc d this memory is
151. e Section 3 5 6 BORROW Imborrow command in FLEXIm Programmers Guide or FLEXIm End Users Guide LM_A BORROW_STAT Type LM_BORROW_STAT Default None Use this attribute to retrieve information about features borrowed on the client machine that is the machine where Imborrow was run This is useful for finding out which features have been borrowed while disconnected from the network After the call to lc_checkout that activates borrowing call FLEXIm Reference Manual August 2004 141 FLEXible API Attributes set by Ic_set_attr 7 3 4 7 3 5 142 LM_BORROW_STAT s lc_get_attr job LM_A BORROW_STAT s for s s s gt next s contains local borrow status The same information is provided by running the FLEX m utility Lmborrow status SEE ALSO e Imborrow command in FLEXIm Programmers Guide or FLEXIm End Users Guide LM_A_CHECK_BADDATE Type int Default False If True and the license that authorizes the application has an expiration date a check is made to see if the system date has been set back on the client node If the checkout fails for this reason the checkout error is LM_BADSYSDATE SEE ALSO e Section 9 1 2 Limited Functionality Demos e Section 13 2 2 Is_a_check_baddate LM_A_CHECK_INTERVAL Type int Default 120 second interval LM_A_CHECK_ INTERVAL controls the rate at which the licensed application sends automatic heartbeat messages to the lic
152. e Section 6 4 12 Ic_heartbeat e Section 7 3 5 LM_A_CHECK_INTERVAL Ic_disconn Drops the connection to the server This functionality is no longer provided by FLEX m use functionality provided by the native operating system Ic_display Returns environment information about the current display This functionality is no longer provided by FLEX m use functionality provided by the native operating system Ic_errtext Returns the English text string corresponding to the FLEX m errno See e Section 6 4 19 lIc_perror e Section 6 4 5 lc_err_info Ic_feat_set Computes the FEATURESET code FEATURESET is no longer used Obsolete FLEXible API Features Obsolete FLEXible API Functions Function Ic_get_feats Description Gets a license key from the FEATURESET line FEATURESET is no longer used Ic_gethostid Returns the hostid for the local host See e Section 6 4 13 Ic_hostid Ic_getid_type Returns the HOSTID of the specified type for the local host See e Section 6 4 13 Ic_hostid e Chapter 15 Vendor Defined Hostid Types Ic_hostname Returns environment information about the current hostname This functionality is no longer provided by FLEX m use functionality provided by the native operating system Ic_isadmin Verifies the specified user is a license administrator This functionalit
153. e licenses to be reclaimed Use of Ic_idle is recommended for end users to take advantage of the TIMEOUT option Ic_idle also affects vendor daemon timeout due to LM_A_TCP_TIMEOUT Ic_idle can be used to bracket a portion of the application code that prompts for user input so that when the user is not using the application the vendor daemon can detect the fact that the application is idle Ic_idle only sets a flag internally in the application it is therefore safe to call as often as necessary A typical use would be lc_idle job 1 Process is idle now wait for input from user lc_idle job 0 Process is no longer idle FLEXIm Reference Manual August 2004 123 FLEXible API Function Descriptions PARAMETERS LM_HANDLE job From Ic_new_job int flag 0 if process is not idle non zero if process is idle RETURN None SEE ALSO e Section 6 4 12 Ic_heartbeat e Section 7 3 17 LM_A_TCP_TIMEOUT e Section 13 2 9 Is_minimum_user_timeout 6 4 15 Ic_init SYNTAX include lm_code h status lc_init job VENDOR_NAME amp code amp lm_ job DESCRIPTION Ic_init initializes FLEX m and creates a license job Subsequent calls to Ic_init create new license jobs each job is independent Ic_init is only to be used with license generators and not in licensed applications shipped to end users Licensed applications use lc_new_job instead for initialization
154. e longer of the developer specified and user specified times will be used The actual time of checkin will vary somewhat since the vendor daemon checks all lingering licenses once per minute If however a new license request is made that would otherwise be denied a check of the lingering licenses is made immediately to attempt to satisfy the new request Linger is useful for programs that normally take under a minute to complete Linger is generally useful only if DUP_GROUP is set in the license file or if dup_group is set in the call to lc_checkout SEE ALSO e Section 7 3 11 LM_A_LICENSE_FMT_VER e Section 3 5 FEATURE INCREMENT Lines e Section 6 4 3 Ic_checkout FLEX m and Multithreaded Applications FLEXI m can be used in multithreaded applications as long as the same FLEX m job is not referenced simultaneously in more than one thread FLEX mis safe for multithreaded applications but FLEX m functions are not re entrant Advanced FLEXIm Topics Multiple Jobs 11 4 Multiple Jobs In the FLEXible API Ic_new_job enables applications to support more than one FLEX m job in a single binary Each job has a separate connection to a license server as well as a independent set of job attributes When a new job is created with lc_new_job all the FLEX m attributes are set to defaults and attributes can be set completely independently for this new job Multiple jobs may be desirable for the following reasons
155. e servers can support a mix of applications which use either native FLEX m or LSAPI but a single executable must use either native FLEX m or LSAPI FLEXIm Reference Manual August 2004 269 LSAPI General Calls 270 Industry Standard Licensing APIs FLEXIm Parameter Limits Limitations such as string lengths are listed here Items that are unlimited are also listed for clarification B 1 FLEX m Parameter General Information B 1 1 Internationalization Support FLEX m provides internationalization support for the following parameter categories Host names Display names User names File names Windows only Feature and package names Contents of NOTIC E ISSU ER V ENDOR_STRING SN asset_info dist_info user_info and vendor_info fields Comments These parameters can contain characters in any language and any codepage including the UTF 8 encoding of Unicode The only codepages that cannot be represented are the UCS 2 encoding of Unicode and EBCDIC SEE ALSO e The chapter entitled Internationalization Support in FLEX m in the FLEXIm Programmers Guide B 1 2 Path Name Formats FLEX m recognizes the following path name specifications e Universal naming convention UNC server myvendor bin e MS DOS naming convention C myvendor bin UNIX naming convention myvendor bin FLEXIm Reference Manual August 2004 271 License File Limits B 2 272 Pa
156. ecessarily uncounted Node locked uncounted licenses do not require a license server A text file implemented for a particular vendor s software by a FLEX m license administrator at an end user site to customize the behavior of the vendor daemon or to enable or restrict the use of the licenses managed by the vendor daemon at that site A text file written by a single vendor daemon Report logs are not human readable the data is compressed and authenticated for use with SAMreport and FLEXbill two Macrovision products that produce reports on license usage A secure 12 to 120 character hexadecimal number which authenticates the readable feature line in the license file ensuring that the text in feature line has not been modified FLEXIm Reference Manual August 2004 21 FLEXIm Terms and Definitions Uncounted license A license that does not restrict the number of uses of an application Uncounted licenses must be node locked to a machine hostid node locked uncounted licenses do not require a license server Vendor daemon The server process that dispenses licenses for the requested features This binary is built by an application s vendor from libraries supplied by Macrovision and contains the vendor s unique encryption seeds Vendor name The name of the vendor as found in 1m_code h Used as the name of the vendor daemon 22 Introduction The License File Overview This chapter provides an overview of t
157. eck out the feature and then use lc_auth_data PARAMETERS LM_HANDLE job From Ic_new_job char feature The desired feature RETURN CONFIG conf The CONFIG struct If no feature found then NULL The CONFIG struct is defined in the header file Imclient h ERROR RETURNS LM_NOFEATURE Specified feature does not exist LM_NOCONFFILE License file does not exist LM_BADFILE License file corrupted LM_NOREADLIC Cannot read license file LM_SERVNOREADLIC Cannot read license data from license server SEE ALSO e Section 6 4 1 lc_auth_data e Section 8 2 3 LM_A_CHECKOUTFILTER LM_A_CHECKOUTFILTER_EX e Section 6 4 3 Ic_checkout FLEXIm Reference Manual August 2004 165 Advanced FLEXible API Functions e Section 8 1 10 Ic_next_conf e Section 7 3 21 LM_A_VD_GENERIC_INFO LM_A_VD_FEATURE_INFO 8 1 8 Ic_get_errno SYNTAX rror lc_get_errno job DESCRIPTION This function returns the most recently set FLEX m error number This value is available after the return of any FLEX m function For more detailed error information which includes the error number use Ic_err_info as an alternative to this function PARAMETERS LM_HANDLE job From Ic_new_job RETURN int error See lmclient h lm_lerr h and lmerrors h for a list of possible FLEX m errors and associated English descriptions SEE ALSO e Section 6 4 5 lc_err_info e Section 6 4 19 Ic
158. ecognized by the security community and recommended for US government work with US government export approval The system comes from Certicom http www certicom com and uses elliptical curve cryptography With CRO the possibility of counterfeiting licenses becomes more remote If you are new to FLEX m or considering adopting CRO see the FLEXIm Programmers Guide for more information about implementing CRO FLEXIm Reference Manual August 2004 211 Security and FLEXIm 11 6 2 Using Imstrip for Additional Security 212 The Imst rip utility is used to obfuscate FLEX m external symbol names FLEX m internal symbol names and vendor specified symbol names in FLEX m enabled libraries and executables Obfuscating these symbol names provides a level of security against reverse engineering your product The lmstrip utility provides the following benefits e Adds security to UNIX FLEX m enabled application binaries e Provides additional security for FLEX m enabled licensing libraries e Allows multiple FLEX m enabled libraries possibly employing different versions of FLEX m to be referenced from the same binary without symbol conflict This utility is located in the plat form directory of the FLEX m Software Development Kit The source shipped with UNIX platforms only is located atmachind lmstrip c UNIX USAGE lmstrip filename f filename n r m mapfile mapfilename strings To display a list of all FLEX
159. ectable by Purify but there may be other FLEXIm Reference Manual August 2004 247 Solving Problems In The Field 16 2 16 3 248 especially I O or system routines which are not reentrant but called by FLEXI m The only way to be certain to avoid this problem would be to disable the automatic heartbeat mechanism and call Ic_heartbeat directly SEE ALSO e Section 6 4 12 Ic_heartbeat Solving Problems In The Field The most important thing is to use Ic_errstring Ip_errstring or ERRSTRING to present the correct error message to your user for diagnosis Here are two common problems that occur in the field License server does not support this feature This indicates that the client and servers are reading two different copies of the license file This can be remedied by inserting a USE_SERVER line after the SERVER line in the license file v5 or later Encryption code in license file is inconsistent FLEX m will report the LM_BADCODE 8 error when e The license file has been mis typed when entered or changed since it was created e The seeds in your application vendor daemon and license generation program differ If you are beginning to integrate your application with FLEX m this error is usually the result of not building all the software components with the same encryption seeds Check lmcrypt c makekey c lsvendor c and your application code carefully to ensure that they are all bu
160. ed User u2 checks out one component thereby reserving the second package license 3 ul write denied Maximum number of package licenses exceeded 4 u3 paint denied Maximum number of package licenses exceeded 5 ul paint granted A paint license is available for user ul 6 ul paint denied The second paint license is checked out by user u2 FLEXIm Reference Manual August 2004 55 PACKAGE Lines pi Requested Checkout User q Result Explanation Feature Attempt 7 u2 write granted User u2 rightfully gets the second write license 8 ul draw granted A draw license is available for each 9 u2 draw granted user 10 ul or u2 draw denied Maximum number of draw licenses exceeded Now consider this variation where one user grabs both package licenses License Requested Checkout User Result Explanation Feature Attempt 1 ul write granted User u1 checks out one component thereby reserving one package license 2 ul write granted User u1 checks out another component thereby reserving the second package license 3 u2 write denied Maximum number paint of package or draw licenses exceeded 56 The License File Syntax 3 7 3 PACKAGE Lines license Requested Checkout User q Result Explanation Feature Attempt 4 ul draw granted Both draw license are reserved for 5 ul draw gr
161. efault regular heartbeats are automatically initiated once a license is checked out Heartbeats are managed via a timer running as a separate thread created on behalf of the application There are four aspects to automatic heartbeat behavior Heartbeats Automatic Heartbeats e Heartbeat thread management Heartbeats are managed by a dedicated thread in the application Heartbeat exchange interval Heartbeats are sent to and acknowledgements received from the license server at a default interval of 120 seconds License server reconnection strategy Reconnecting to a lost license server is tried every 60 seconds for up to 5 attempts There are three possible outcomes with automatic heartbeats when reconnection is attempted after the connection to the license server is lost Reconnection to the license server succeeded Reconnection to the license server was attempted and failed but more attempts will be made Reconnection to the license server was unsuccessful after the retry limit was reached Recovery from a lost license server If connection is not re established after five retries the application by default exits with the error message Lost License cannot re connect UNIX stderr WINDOWS dialog box 12 1 1 Controlling Automatic Heartbeat Behavior Various aspects of automatic heartbeat default behavior can be overridden by setting the appropriate FLEXible API attributes via lc_set_attr Table 12 2 li
162. empts after license server connection is lost before calling the exit handler defined below lc_set_attr lm_job LM_A_RETRY_COUNT LM_A_VAL_TYPE 3 Register the exit handler callback exitcall The default is the system s exit routine lc_set_attr lm_job LM_A_USER_EXITCALL LM_A VAL TYPE exitcall Check out the feature f1 if lc_ checkout lm_job f1 1 0 1 LM_CO_NOWAIT amp code LM_DUP_NONE lc_perror lm_job checkout failed exit lc_get_errno lm_job Heartbeats License Server side Considerations Start the manual heartbeat timing loop This loop sends a heartbeat message with every iteration while 1 When the following call to lc_heartbeat returns num_reconnects will contain the number of successful license server reconnects in the last num_minutes ES if hbstat lc_heartbeat lm_job amp num_reconnects num_minutes Connection to license server is lost and an attempt to reconnect unsuccessful Monitor hbstat and respond as appropriate to your license policy After LM_A_RETRY_COUNT number of reconnect attempts 3 in this example control automatically transfers to the exit handler exitcall Loop timing and application code for this license job occur here end of heartbeat timing loop lc_checkin lm_job feature 0 lc_free_job 1m_job exit 0 Exit handler callback This is invoked automatically by FLEX1m after
163. ense server To disable automatic heartbeat messages set LM_A_CHECK_INTERVAL to 1 as well as setting LM_A_RETRY_INTERVAL to 1 The minimum value for LM_A_CHECK_INTERVAL is 30 seconds The results of possible settings of this variable are Variable Setting Result check_interval 1 Automatic heartbeats are disabled Controlling Licensing Behavior 7 3 6 7 3 7 7 3 8 FLEXible API Attributes set by Ic_set_attr check interval gt 0 lt 30 Value is ignored and current interval is unchanged check_interval gt 30 Timer interval If automatic heartbeats are disabled you must call Ic_heartbeat periodically to check the status of the license server SEE ALso e Section 6 4 12 Ic_heartbeat e Section 7 3 16 LM_A_RETRY_COUNT LM_A_RETRY_INTERVAL e Heartbeats chapter in the FLEXIm Programmers Guide LM_A_CKOUT_INSTALL_LIC Type int By default a successful checkout automatically updates the registry VENDOR_LICENSE_FILE setting where VENDOR is your vendor name to include the license file location that was used for the checkout This can be disabled by setting this attribute to 0 Default None SEE ALSO e Registry and HOME flexlmrc e Section 7 3 1 LM_A APP DISABLE CACHE READ LM_A_FLEXLOCK Type int Default Off Turns on FLEXlock capability This must be enabled to use FLEX ock but application security is poorer FLEX ock is available only on Windo
164. ent machine will be denied a license See Section 18 4 Windows Terminal Server Support for more information 3 5 23 USER_BASED USER_BASED n Optional field If USER_BASED appears then licenses can only be used by users INCLUDEd for this feature in the end user options file The purpose is to limit the use to a particular number of users but allow the end user to determine which users If n is specified then the number of users which can be INCLUDEd is limited to n Otherwise the limit is the num_lic field If an INCREMENT appears where some licenses are USER_BASED and some are not the vendor daemon tracks these in separate license pools 3 5 24 VENDOR_STRING VENDOR_STRING 48 The License File Syntax 3 5 25 3 5 26 FEATURE INCREMENT Lines Optional field Vendor defined license data If a checkout is conditional on the contents of the vendor string then LM_A_CHECKOUTFILTER is the best way to do this If the VENDOR_STRING is set you will probably also need to set 1s_compare_vendor_ in lsvendor c The VENDOR_STRING is optionally configured as a pooling component in which case if the string differs in any way for two INCREMENT lines for the same feature name they are pooled and counted separately SEE ALSO e Section 6 4 1 lc_auth_data e Section 8 2 3 LM_A_CHECKOUTFILTER LM_A_CHECKOUTFILTER_EX e Section 13 2 4 Is_compare_vendor_on_increment and ls_compare_vendo
165. ents to lmgrd each time it is started as a service A string of parameters with embedded spaces needs to be enclosed in double quotes One or more of the following can be specified local Restricts the 1mdown command to be run only from the same machine where lmgrd is running options options_file_path Specifies the full path to the lmgrd options file This file is used to configure the Microsoft Windows event logging service for 1Imgra events If this parameter is omitted lImgra by default looks for a file called lmgrd opt located in the same directory as the Imgrd binary e x 1lmdown Disables the 1mdown command no user can run 1mdown e x mremove Disables the Imremove command no user can run lmremove See Section 10 1 Imgrd Command Line Syntax for more information on these three arguments Other Imgrd parameters are not supported here r Remove service_name service 262 Windows Platform Specific Notes Installing Imgrd as a Service Using installs After installs exe is run successfully Imgrd is installed as a Windows service and will be started automatically each time your system is booted If you wish to customize the installs program the source code is included in the file machind installs c EXAMPLES e To install Imgrd as a service installs e C Program Files flexlm i86_n3 lmgrd c C mylicenses sample lic 1 C mylogfiles sample dl A n Myvendor License Manager where C
166. erence Manual August 2004 ili 3 5 6 BORROW 3 00 Seon ohn nte a ral a ed e eli 42 JT DUP GROUP A ea 42 30 87 ELOATIOK cis era Vaid ain eR taa dea dia a 43 3 39 HOST BASED ica recia Pa a tind e E EE bes Hh 43 33 10 HOSTID au ads we wie we ele ee aid 44 3 95 11 ISSUED ts so ences A s 45 3 5212 ISSUER cuotas ls da cinema ole 45 33 13 MINIMUM to a lt IA Rane CEREN 45 30 14 NOTICE coi ci A A at eR eras 45 IS TS OVERDRAFT raras naaa pida 45 3 9 16 PLATFORMS to Sal es ee a Se iba 45 ISIT SIGN ig sete Bas Saeed Ae ges Br he ee 46 A ESN Ss ches hehe ews downed dome owhd dan tae lt 4 46 3519 START oia Castes tee steed ahead ete nese ew A 47 3 39 20 SUITE DUP GROUP as 47 33 21 SUPERSEDE sisson oa eda Seagate di pta en a eb 47 3322 TSE OK o eee t E seu teats 4 48 3 59 23 USER BASED ois baie wit is wie ie aa hd 48 3 5 24 WENDOR_STRING 0 0 0 cee ee 48 3 929 ASE MO e ds TA A A e 49 ZO dist MIO A A dye at a ese A ARE Rd 49 A A EN 49 325528 e s r info at a ds o 50 39 29 Vendor INIO ee deel peice a A Bb E eae ea hi A 50 3 6 UPGRADE Lines 0 0 eee 50 3 1 PACKAGE Dine is onde 52 3 7 1 PACKAGE Example 0 0 0 0c cece eee eee ee 54 3 7 2 PACKAGE SUITE_RESERVED Example 54 3 7 3 PACKAGE SUITE Example 04 57 3 8 Decimal Format Licenses 0 0 0 cece eee eee eee 61 3 8 1 Decimal Format Limitations 0055 62 3 8 2 Example De
167. es one of the following actions Invokes this filter function again with a subsequent authenticated FEATURE line for the license request If there are no more candidate FEATURE lines Ic_checkout fails and sets the FLEX m error number to LM_LOCALFILTER the license is not checked out SEE ALSO e Section 6 4 3 Ic_checkout e Section 8 2 3 LM_A_CHECKOUTFILTER LM_A_CHECKOUTFILTER_EX e Section 8 2 17 LM_A_VENDOR_CALLBACK_DATA FLEXIm Reference Manual August 2004 181 Advanced FLEXible API Attributes 8 2 5 8 2 6 8 2 7 182 LM_A CRYPT_CASE SENSITIVE Type short Default Case insensitive comparison If specified as a non zero integer LM_A_CRYPT_CASE_SENSITIVE will cause the output of the authentication function to be compared to the code in the license file with a case sensitive comparison LM_A _DIAGS ENABLED Type short Default On 1 This option allows FLEX m to produce some diagnostic output for failures of the Ic_checkout call if the environment variable FLEXLM_DIAGNOSTICS is set If LM_A_DIAGS_ENABLED is set to 0 this diagnostic information is unconditionally disabled The FLEXLM_DIAGNOSTICS environment variable can be used by your end users to obtain more information if a checkout fails If FLEXLM_DIAGNOSTICS is set an Ic_perror call is made If FLEXLM_DIAGNOSTICS is set to 2 then in addition to the Ic_perror call the arguments to lc_checkout except for
168. es that UNIX st rip leaves intact If any external FLEX m symbol is referenced from a shared library which is very rare use lmstrip e which leaves the FLEX m external symbols names intact but still obfuscates the internal FLEX m symbol names Advanced FLEXIm Topics Security and FLEXIm Because symbol names do not appear in fully linked Windows binaries this procedure is not needed on Windows platforms PROVIDING ADDITIONAL SECURITY FOR LICENSING LIBRARIES UNIX scenario 1 ld r my_routines o liblmgr a o ofile o ofile o now includes both the necessary FLEX m functions referenced from my_routines o and the contents of my_routines o 2 lmstrip ofile omy_symbol_1 my_symbol_2 my_symbol_3 This obfuscates the FLEX m symbol names as well as the additional vendor specified symbols 3 You then ship ofile o to your customers knowing that the FLEX m symbol names and the specified vendor symbol names are not detectable in the resulting object file Windows scenario l lib my_routines lib lmgr lib out ofile lib ofile 1ib now includes the contents from both my_routines liband lmgr lib 2 Imstrip o mystrings ofile lib Where myst rings contains lines similar to the following my_symbol_1 my_symbol_2 my_symbol_3 This obfuscates the FLEX m symbol names as well as the additional symbol names specified in myst rings 3 lib ofile lib This re sorts of ile 1ib so that subsequent linking can resolve the newly obfuscated s
169. es to be returned early This is the default setting 1 Allow licenses to be returned early SEE ALSO e Section 8 3 1 Is_borrow_in e Section 8 3 2 Is _borrow_init e Section 8 3 3 Is_borrow_out Is_conn_timeout int ls_conn_timeout MASTER_WAIT How long to wait for a connection 1s_conn_timeout is the amount of time in seconds that vendor daemons will wait for connections from vendor daemons on other nodes when using redundant servers It should normally not be changed Is_do_checkroot UNIX Only int ls_do_checkroot 0 Perform check that we are running on the real root To require that your vendor daemon be running on a file system which has its root directory as the real root directory of the disk set this option This prevents an end user from cloning part of the UNIX file hierarchy and executing the daemon with a chroot command If this were done the vendor daemon locking would be bypassed and the user could run as many copies of your vendor daemon as he desired Theft by using chroot is considered to be an obscure difficult kind of theft The user has to have root permission and setting up a phony directory is a non trivial task It requires that the necessary parts of the OS from etc dev bin etc be copied into this phony directory and is an ongoing administrative hassle FLEXIm Reference Manual August 2004 191 Advanced Vendor Variables 8 3 7 8 3 8
170. eywords are not involved in license authentication This means they can be modified and the license will remain valid The signature is required to be last Table 3 2 summarizes the FEATURE INCREMENT fields and keywords Table 3 2 FEATURE INCREMENT Fields and Keywords Keyword Positional Fields in required order Feature Name Vendor Daemon Name Feature Version Expiration Date Number of Licenses Authenticated Vendor Keywords BORROW DUP_GROUP FLOAT_OK HOST_BASED HOSTID ISSUED MINIMUM OVERDRAFT PLATFORMS START SUITE_DUP_GROUP SUPERSEDE FLEXIm Reference Manual August 2004 37 FEATURE INCREMENT Lines Table 3 2 FEATURE INCREMENT Fields and Keywords Continued Keyword TS_OK USER_BASED VENDOR_STRING Informational Vendor Keywords ISSUER NOTICE SN Unauthenticated Keywords asset_info dist_info user_info vendor_info sort Signature SIGN An INCREMENT line can be used in place of a FEATURE line as well as to incrementally add licenses to a prior FEATURE or INCREMENT line in the license file Only the first FEATURE line for a given feature is processed by the vendor daemon If you want to have additional copies of the same feature for example to have multiple node locked counted
171. features use multiple INCREMENT lines To cause multiple FEATURE lines for the same feature to be recognized set ls_use_all_feature_lines set in lsvendor c for your vendor daemon The original behavior of FEATURE line is then unavailable to that application Notify your end user if you set ls_use_all_feature_lines 38 The License File Syntax FEATURE INCREMENT Lines There are two formats for FEATURE pre v3 0 and current The older format 1s still understood and correct with new clients and servers but the current format is more flexible LICENSE POOLS INCREMENT lines form license groups called license pools based on the following fields e feature name e version e DUP_GROUP e FLOAT_OK e HOST_BASED HOSTID e PLATFORM e USER_BASED e VENDOR_STRING if configured by the vendor as a pooling component If two lines differ by any of these fields a new license pool is created in the vendor daemon and this group is counted independently from other license pools with the same feature name A FEATURE line does not give an additional number of licenses whereas an INCREMENT line always gives an additional number of licenses Consider the following example that demonstrates license pooling SERVER speedy 08002b32b161 VENDOR demo INCREMENT f1 demo 2 0 permanent 1 SIGN 2B8F621C172C INCREMENT f1 demo 2 0 permanent 2 SIGN 2B9F124C142C e INCREMENT the server adds up licenses for all lines for the same feature name forming
172. fectively charges more for a more powerful system The CAPACITY keyword enables a checkout multiplier implemented internally in the licensed application with the LM_A_CAPACITY attribute LM_A_CAPACITY is set using Ic_set_attr available in the FLEXible API If Ic_checkout requests 2 licenses and LM_A_CAPACITY is set to 3 six licenses will be checked out Capacity licensing is implemented by adding the CAPACITY keyword to the FEATURE line and setting LM_A_CAPACITY in the application with lc_set_attr job LM_A_CAPACITY LM_A_VAL_TYPE i Both components must be implemented the CAPACITY keyword on the FEATURE line and the LM_A_CAPACITY attribute set in the application for capacity licensing to be enabled If one component is missing check out requests proceed without applying a multiplier to the requested license count The LM_A_CAPACITY attribute must be set before the first connection to the server usually lc_checkout and cannot be reset once set For example you can license your product based wholly or in part on the number of CPUs on the licensed application machine Processors enabled with Intel s Hyper Threading Technology first seen in the Intel Xeon processor family appear as two logical processors to the operating system Processors that implement Hyper Threading Technology provide improvements in performance resource utilization and processing throughput as compared to single processors without Hyper Threading
173. ffect on the number of licenses consumed That is the FLEX m client library checks out only as many additional licenses for the feature as necessary to reach the count specified in the checkout request For example If an initial checkout request which asks for two licenses for feature f1 lc_checkout lm_job f1 1 0 2 LM_DUP_NONE is followed by a second call which asks for five licenses for the same feature lc_checkout lm_job f1 1 0 5 LM_DUP_NONE the second call checks out only three additional licenses 5 minus 2 If the second call asks for the same or fewer number of licenses than were already checked out the second call does not check out additional licenses Advanced FLEXible API Features Advanced FLEXible API Attributes To force identical checkout requests instead to have an incremental effect on the number of consumed licenses include each call to lc_checkout in its own license job Alternatively use the LM_A_ CHECKOUT_DATA attribute to set a unique checkout data string to the job just prior to the call to lc_checkout This causes the second or subsequent request to check out exactly the number of licenses specified in the call to lc_checkout regardless of the number asked for in previous requests For example Check out 2 licenses for fl label them first checkout lc_set_attr lm_job LM_A CHECKOUT_DATA first checkout lc_checkout 1m_job f1 1 0
174. fined Hostid You will use the vendor daemon license generator and client application you just built to test a vendor defined hostid 1 Create a license file that contains a VENDOR line with the vendor daemon you just built Change the hostid on the SERVER line to VDH 12345678 Run this license file through the newly built Imcrypt Start your license server pointing to this license file Run 1lmflex You should be able to check out f1 uN Exit lmflex and stop the license server 15 4 Additional Steps for Production Use of a Vendor Defined Hostid Type To implement a real vendor defined hostid type you must write a function that can find the hostid that you want to use then use that function s return value instead of the fixed value VENDEF_ID in strncpy in vendor_hostid c if idtype VENDEF_ID_TYPE h gt type VENDEF_ID_TYPE strncpy h gt id vendor VENDEF_ID MAX_HOSTID_LEN h gt id vendor MAX_HOSTID_LEN 0 return h FLEXIm Reference Manual August 2004 245 Additional Steps for Production Use of a Vendor Defined Hostid Type 246 Vendor Defined Hostid Types Debugging Hints 16 1 Debugging Your Application Code There are several issues to be aware of when debugging your FLEX m integrated application Some of these are described in this chapter e If you are experiencing problems on only one platform or if you run on only a single platform please che
175. five consecutive reconnection attempts are made to a lost license server int exitcall char feature printf I am in the exit callback for feature s n feature exit 1 12 3 License Server side Considerations The license server waits 2 hours default to hear from the FLEX m application before checking in its licenses The LM_A_TCP_TIMEOUT attribute is used to adjust default timeout value for the TCP IP port 0 means no TCP IP port timeout 1s_minimum_user_timeout in lsvendor c adjusts general timeout not just TCP IP related The end user can adjust this timeout value further with the TIMEOUT and TIMEOUTALL options file keywords see the FLEXIm End Users Guide for more details FLEXIm Reference Manual August 2004 225 License Server side Considerations 226 Heartbeats Vendor Daemon The FLEX m installation program on UNIX builds a vendor daemon either a demo vendor daemon or your own depending on your instructions A demo vendor daemon is provided in your Windows installation but you have to rebuild your Windows FLEX m SDK to build your own vendor daemon vendor or vendor exe Your vendor daemon can be customized via variables in machind 1svendor c but changes to this file are normally neither suggested nor required 13 1 Configuring Your Vendor Daemon To configure your vendor daemon 1 Edit 1m_code h to change the VENDOR_NAME field to your vendor daemon name 2 Customize 1svendor c if neces
176. g 69 It_heartbeat 69 It_perror 70 It_pwarn 70 It_warning 71 overview 17 PERROR 70 PWARN 70 WARNING 71 TS_OK 48 typographic conventions Xiv U uncounted license definition 22 UPGRADE line syntax 50 USE_SERVER line 36 USER_BASED 48 user_info 50 yV vendor daemon automatic reconnection 149 FLEXIm Reference Manual August 2004 317 definition 22 XOpenDisplay 183 detecting daemon death 142 XtApplnitialized 183 limits 274 path on VENDOR line 35 VENDOR line options file path 35 port 35 syntax 35 vendor daemon path 35 vendor name 35 vendor name 41 definition 22 on VENDOR line 35 vendor_info 50 VENDOR_LICENSE_FILE HOME flexlmrc 98 140 and LM_A_LICENSE_DEFAULT 145 Windows registry 98 140 VENDOR_STRING 48 and ls_compare_vendor_on_ 228 vendor defined checkin callback 229 vendor defined checkin filter 230 vendor defined checkout filter 231 vendor defined hostid defining 235 241 limits 274 LM_A_VENDOR_ID_DECLARE 155 verifying license on install 160 version 41 Visual Basic 257 W WARNING 71 wide area network limits 275 Windows platform notes 257 X X Display name 183 318 FLEXIm Reference Manual August 2004
177. g and lc_next_conf are usually needed only with LM_A_VD_GENERIC_INFO or LM_A VD_FEATURE_INFO To get authenticated information from a FEATURE line you must first check out the feature and then use Ic_auth_data PARAMETERS LM_HANDLE job From Ic_new_job char feature The desired feature line RETURN CONFIG conf The CONFIG struct If none found then NULL pointer to Declare CONFIG pos 0 uSe pos CONFIG pos for argument Internally updated by Ic_next_conf to next license file entry ERROR RETURNS See error returns for Ic_get_config FLEXIm Reference Manual August 2004 169 Advanced FLEXible API Functions 8 1 11 Note 170 EXAMPLE CONFIG pos 0 conf while conf 1c_next_conf job myfeature pos FE awt RS SEE ALSO e Section 6 4 1 Ic_auth_data e Section 8 2 3 LM_A_CHECKOUTFILTER LM_A_CHECKOUTFILTER_EX e Section 6 4 3 Ic_checkout e Section 8 1 7 Ic_get_config e Section 7 3 21 LM_A_VD_GENERIC_INFO LM_A_VD_FEATURE_INFO Ic_remove SYNTAX status lc_remove job feature user host display DESCRIPTION Removes the specified user s license for feature This is used by the 1mremove command and has the same restrictions regarding the Imadmin group lc_remove normally is only used when the client s system has had a hard crash and the server does not detect the client node failure If lc_remove is
178. gal int num_lic The number of licenses to check out Must be gt 0 int flag The checkout option flag Possible values for flag are LM_CO_NOWAIT Do not wait non blocking LM_CO_WAIT Wait return when license is granted blocking LM_CO_QUEUE Queue request return immediately This request will give you the license if it is available You can find out if you hold the license by calling Ic_status If there are multiple license pools this queues from only the first license pool in the list 94 FLEXible API FLEXible API Function Descriptions LM_CO_LOCALTEST With this flag the license file is tested for po VI i errors that would prevent a license checkout a license is not consumed when Ic_checkout is used with this flag In particular LM_MAXUSERS and LM_USERSQUEUED are not detected but other checkout errors are detected For example you might want to gray out a menu item if a particular feature is not present in the license file If you call Ic_checkout with the LM_CO_LOCALTEST flag use the function Ic_test_conf to retrieve the license file line for the tested feature lc_auth_data won t work with the LM_CO_LOCALTEST flag This can only be done after the most recent call to Ic_checkout Testing a license file with this flag causes a connection to the license server system that lasts as long as the current job Therefore the job in which the test is performed is irrevocably connec
179. good until the year 2027 This is probably a bad date FLEXIm key data has expired The FLEX m demo vendor keys have expired Contact Macrovision for new demo keys FLEXIm not initialized A FLEX m function was called before Ic_new_job was called Always call Ic_new_job first Server did not respond to message UDP communications failure UDP communications are not guaranteed FLEX m makes a best effort to recover from lost and garbled messages but this indicates a failure Request rejected by vendor defined filter Ic_checkout failed because of the vendor defined routine which is set in lsvendor c ls_outfilter No FEATURESET line present in license file Ic_ck_feats called but no FEATURESET line in license file 284 FLEXIm Status Return Values 00 LM_BADFEATSET 56 LM_CANTCOMPUTEE EATSE Ou LM_SOCKETFAIL 58 LM_SETSOCKFAIL 59 LM_BADCHECKSUM 61 LM_SERVNOREADLIC FLEXIm Reference Manual August 2004 Error Number Table Incorrect FEATURESET line in license file Error return from Ic_ck_feats Cannot compute FEATURESET line Error return from lc_ck_feats which occurs because Ic_feat_set can not compute the FEATURESET line This can happen because there are no FEATURES in the file socket call failed This can occur when the UNIX OS runs out of system
180. h no parameters If it returns 0 your routine has either checked out the feature or rejected the checkout request If it returns 1 then the normal server checkout occurs If 0 is returned and the checkout fails set the error code appropriately with Ic_set_errno To obtain the parameters of the current checkout call use the Is_get_attr call This is only for use in the 1s_out filter callback ls_get_attr attr amp value where attr An attribute specified in 1s_attr h char value Value of the attribute Is_get_attr operates in the same manner as Ic_get_attr ls_get_attr allows you to retrieve the values of the feature name user host display etc for use in your filtering function The Is_checkout vendor daemon routine is only for use in 1s_outfilter callbacks ls_checkout feature num lic wait who version dup_sel linger sign 0 1 PARAMETERS char feature Feature desired char num_lic Number of licenses char wait Wait until available flag If set to 1 the request is queued if a license is not available CLIENT_DATA who The user char version Version number of feature char dup_sel Duplicate license selection criteria FLEXIm Reference Manual August 2004 231 Vendor Variables char linger How long the license is to linger char sign Signature from FEATURE line RETURN 0 OK license checked out lt gt 0 Error Note Is _get_attr
181. hat was passed to the call to Ic_checkout CONFIG config A pointer to the CONFIG struct representing the candidate feature void vendor_data LM_A_CHECKOUTFILTER_EX only A pointer to either vendor defined data set via the LM_A_VENDOR_CALLBACK_DATA attribute or NULL FLEXIm Reference Manual August 2004 179 Advanced FLEXible API Attributes 8 2 4 180 RETURN VALUES The return value from this function effects the outcome of the current checkout request in the following ways e Ifo is returned Ic_checkout continues to evaluate the FEATURE line in an attempt to satisfy the license request Ifa non zero value is returned Ic_checkout does not continue to evaluate the current FEATURE line but instead takes one of the following actions Invokes this filter function again with a subsequent candidate FEATURE line for the license request If there are no more candidate FEATURE lines Ic_checkout fails and sets the FLEX m error number to LM_LOCALFILTER the license is not checked out SEE ALSO e Section 6 4 3 Ic_checkout e Section 8 2 4 LM_A_CHECKOUTFILTERLAST_EX e Section 8 2 17 LM_A_VENDOR_CALLBACK_DATA LM_A_CHECKOUTFILTERLAST_EX Type Pointer to a function returning int Default None DESCRIPTION The function pointer LM_A_CHECKOUTFILTERLAST_EX is set to point to a checkout filter callback function This filter function is invoked after Ic_checkout
182. he license file format and examples of license file types Once you have an idea of the license file format for your FLEX m enabled product proceed to Chapter 3 The License File Syntax for specific syntactical information 2 1 Format of the License File A license file consists of the following sections Server Information This section appears in the license file if a license server is used that is if any features are counted The following types of lines can appear in this section SERVER lines The SERVER line s contain information about the node s where lmgrd is running VENDOR line The vendor specific VENDOR line contains information about the vendor daemon that runs on the license server node s USE_SERVER line A USE_SERVER line if used usually follows the SERVER line and indicates that a client application should not process the rest of the license file itself but should check out the license directly from the license server Package Information This section defines how individual components are grouped into packages There is only one type of line in this section PACKAGE line FLEXIm Reference Manual August 2004 23 Format of the License File Note 24 e License Rights Information This section includes information which entitles feature usage whether the features are used individually or as components in a package This information is required in a license file read directly by the li
183. he original complement of licenses from the license server FLEXIm Reference Manual August 2004 115 FLEXible API Function Descriptions 116 e It informs the application of a number of states that may indicate attempted tampering with the license server To use Ic_heartbeat you must first turn off the automatic mechanism before the first license checkout lc_set_attr lm_job LM_A_CHECK_INTERVAL LM_A VAL TYPE 1 lc_set_attr lm_job LM_A_RETRY_INTERVAL LM_A VAL TYPE 1 Heartbeat messages ensure that licenses are re checked out from a restarted server Heartbeats are not needed for the server to retain a client s license the server retains the license until the client exits If Ic_heartbeat is called the client will automatically reconnect and re checkout from a license server that has restarted It also informs the application of a number of states that may indicate attempted tampering with the license server e The return value if non zero indicates that the license server is down and how many reconnect attempts have been made This information can be used for example to inform the end user the license server is down and possibly to deny use after a specified number of failures e The arguments num_reconnects and num_minutes if used can indicate the rate a server has been stopped and started possibly signifying attempted theft PARAMETERS LM_HANDLE job From Ic_new_job int Pointer
184. he vendor daemon WINDOWS PLATFORMS This string if specified is used to override the display name as derived from the WTSQuerySessionInformation call from the Platform SDK Terminal Services API The most common use of this attribute is for setting the display to the remote hostname in a Terminal Server environment UNIX PLATFORMS This string if specified is used to override the display name as derived from the UNIX ttyname system call The most common use of this attribute is for setting the display to the X Display name Unfortunately the only reliable way of obtaining the name of the X Display is via a call to an X based routine Therefore this can only be done by the X based application after XOpenDisplay or XtApplnitialize has been called The Display name is available via the X macro DisplayString display In addition it is essential to note that there are at least three possible aliases for using the monitor attached to the computer in use localhost 0 unix 0 and 0 If any of these are used LM_A_DISPLAY_OVERRIDE should use the result of gethostname instead Finally it may be safest to use the IP address as a string to avoid the problem of aliases for a particular display host FLEXIm Reference Manual August 2004 183 Advanced FLEXible API Attributes 8 2 9 Note LM_A_HOST_OVERRIDE Type char Default No override of host name This string if specified will be used to over
185. heck out a feature you must call the LM_USE_FLEXLOCK macro before the call to the Ic_checkout LM_USE_FLEXLOCK can be used with the Trivial Simple or FLEXible API Advanced FLEXIm Topics 11 6 11 6 1 Security and FLEXIm LM_USE_FLEXLOCK status l1c_checkout job feature version num_lic flag code dup_group CHECKING OUT MORE THAN ONE FEATURE WITH FLEXLOCK ENABLED If you are using FLEX ock and your application checks out more than one feature use the FLEXible API You will need a flag indicating that the first checkout was authorized by FLEX ock In the following example code the flag is called flexlock_flag and is initialized to 0 After the first successful call to Ic_checkout returns call CONFIG conf extern int flexlock_flag conf lc_auth_data job feature if conf gt idptr amp amp conf gt idptr gt typ HOSTID_FLEXLOCK flexlock_flag 1 Before all subsequent calls to Ic_checkout check the value of flexlock_flag If flexlock_flagissetto false proceed with the call if flexlock_flag lc_checkout feature2 0 feature2 enabled Security and FLEX m Counterfeit Resistant Option CRO FLEX m offers the Counterfeit Resistant Option CRO Without CRO FLEX m utilizes the standard FLEX m license key which uses a proprietary non public key digital signature method CRO offers a standard public key system which is r
186. hronization are v8 2 or later see Section 8 3 11 Is_user_lock Windows only e UNIX Platforms Use this mechanism regardless of vendor daemon version 8 3 11 Is_user_lock Windows only char ls_user_lock NULL By default only one instance of a vendor daemon with the same name can run on the same machine at one time If you want to prevent multiple vendor daemons that have different vendor names from running simultaneously use this callback mechanism FLEXIm Reference Manual August 2004 193 Advanced Vendor Variables Initialize 1s_user_lock with a pointer to your routine which returns a string containing either one lock name or a list of space delimited lock names The lock names are used in a lock out mechanism to prevent multiple copies of the vendor daemon from running on the same machine Lock names have the following restrictions e The maximum number of lock names supported per vendor daemon is 30 e Each lock name can contain a maximum of 179 characters and any ASCII 99 66 character except or space Lock names are case sensitive Any other vendor daemon using one or more of these lock names is prevented from running on the same machine at the same time The default value includes one lock name the name of the vendor daemon If 1s_user_lock is NULL then this default lock name is used This mechanism is provided as a callback to so that the set of lock names can be constructed
187. icense line template Example FEATURE 2 demo 1 0 permanent uncounted start 03 jan 2003 HOSTID 1234 To keep the date the same in an already existing license key leave the license key as is FEATURE 2 demo 1 0 permanent uncounted 6E06CC47D2AB30542134 HOSTID 1234 COMPATIBILITY ISSUES V6 applications even those accepting 12 character license keys will accept licenses with long 20 character license keys Pre v6 applications will not accept licenses with 12 character license keys License generators Imcrypt makekey issue long license keys when verfmt is set to a version less than 6 LM_VER_BEHAVIOR in machind 1m_code2 h set to LM_BEHAVIOR_V5_1 or older will set license keys to be long and start dates in the license keys However this can be overridden in the code with Ic_set_attr job LM_A LKEY_LONG LM_A VAL TYPE 0 and Ic_set_attr job LM_A_LKEY_START_DATE LM_A_VAL_TYPE 0 which must be set in the application license generator and vendor daemon FLEXIm Reference Manual August 2004 301 Obsolete License File Features Existing companies can successfully use short license keys and may very well want to but must obey the following rules e Ifa site wants to use older products then you must use verfmt to create a license with long keys Both old and new products will accept these licenses e Ifa site is completely converting to products usi
188. ile Windows Only path or server name 6 2 2 Job Handling 6 2 3 84 Each licensed application must establish at least one connection to a license server This connection is called a job and is managed by a job handle Job handling API functions manage job handles Table 6 3 lists these functions Table 6 3 Job Handling Function Name Description Ic_first_job Locates the first job on the list of jobs Ic_free job Frees the memory associated with a job Ic_new_job Initializes FLEX m and creates a new job Ic_next_job Walks the list of jobs Heartbeat Management and Communication Heartbeat exchange is the mechanism by which the licensed application keeps track of the license server status The vendor implements heartbeats as either automatic or manual If manual heartbeats are implemented the API functions and attributes in Table 6 4 are used Table 6 4 Heartbeat Management and Communication Function or Attribute Name Description Functions Ic_heartbeat Exchanges heartbeat messages with the license server Used for manual heartbeat implementations FLEXible API FLEXible API Functions by Category Table 6 4 Heartbeat Management and Communication Continued Function or Attribute Name lc_idle Description Informs the license server when the licensed application is idle Attributes LM_A_CHECK_INTERVAL Controls the licensed
189. ilt with the same encryption seeds If this is the case you simply need to make sure that your application Imcrypt makekey and your vendor daemon have all been rebuilt since the last time that you changed 1m_code h and that there is only one 1m_code h file Multiple Vendors Using FLEX m at a Single End User Site In the case where multiple software vendors install FLEX m based products at a single end user site the potential for license file location conflicts arises This section summarizes strategies that allow for a minimum of end user inconvenience Debugging Hints Multiple Vendors Using FLEXIm at a Single End User Site There are basically two cases involved at an end user site when more than one software vendor installs products CASE 1 ALL PRODUCTS USE THE SAME LICENSE SERVER NODE S In this case there are three possible solutions The end user can keep both license files separate running one Imgrd with a license file list containing both files The end user can keep the license files separate running two lmgrds one for each license file There are no drawbacks to this approach because the lmgrd processes require few system resources When using two separate license files make sure the port numbers are different or leave them blank for FLEX m to automatically find an open port e You can combine license files by taking the set of SERVER lines from any one license file and add all the other lines VENDOR F
190. imum length is MAX HOSTID_LEN Solaris HOSTID_LONG 32 bit hostid All HOSTID_ETHER Ethernet address SuSE Linux All HOSTID_ETHER Ethernet address Enterprise HOSTID_FLEXID9 FLEXID 9 Server 8 1 e Mfg Aladdin 32 bit only Knowledge Systems e Device HASP 4 M1 USB memory key The following table lists the hostid types common to all platforms id_type Description HOSTID_COMPOSITE Composite hostid if defined See Chapter 14 Composite Hostids and Section 8 1 9 Ic_init_simple_composite HOSTID_DEFAULT Default hostid type on the system HOSTID_DISPLAY Display name HOSTID_HOSTNAME Node name HOSTID_INTERNET Internet IP address HOSTID_USER User name 122 FLEXible API FLEXible API Function Descriptions id_type Description HOSTID_VENDOR Vendor defined hostid if defined See Chapter 15 Vendor Defined Hostid Types RETURN int status 0 if successful FLEX m errno otherwise ERROR RETURNS LM_FUNCNOTAVAIL Vendor keys do not support this id_type SEE ALSO e machind 1lmclient h for valid hostid type definitions e FLEXIm End Users Guide Appendix A Hostids for FLEXIm Supported Machines for a list of the default hostid for each supported platform 6 4 14 Ic_idle SYNTAX void lc_idle job flag DESCRIPTION Informs FLEX m when the process is idle Ic_idle enables the end user feature inactivity TIMEOUT to allow idl
191. ine must appear after the PACKAGE line to work correctly Limited Functionality Demos FLEX m does do some security checks to prevent users from setting system dates back Though date setback detection can be circumvented most honest users customers who would pay for licenses that cannot be stolen find that working with incorrect system dates is annoying and too public a form of theft For companies that are more concerned with security there are several things that can be done to make date setback less feasible PROMINENTLY DISPLAY EXPIRATION DATE After a successful checkout call conf lc_auth_data job feature to get an authenticated copy of the CONFIG struct that authorized the checkout Put the expiration date CONFIG gt date in a prominent place in the GUI so that the date setback detection is more public PROVIDE AN INSISTENT REMINDER If it is an expiring evaluation version periodically do something annoying perhaps a popup that appears every few minutes which encourages the user to purchase the product DISABLE SOME FUNCTIONALITY A classic example is a word processing program that alters saved files so that when printed the word EVALUATION is printed in large letters across every page This allows evaluators full functionality without reasonable utility License Models 9 2 9 2 1 Lenient Licensing Report Log and OVERDRAFT The application needs to detect that the HOSTID is
192. int print Unused RETURN int status 0 server not shut down lt gt 0 server shut down ERROR RETURNS LM_FUNCNOTAVAIL Vendor keys do not support this function LM_NOTLICADMIN You are not an authorized license administrator LM_CANTREAD Cannot read data from license server SEE ALSO e Chapter 10 The License Manager Daemon 8 1 13 Ic_test_conf SYNTAX conf lc_test_conf lm_job DESCRIPTION Retrieves the license file line for the most recently tested feature A feature is tested but not checked out when the LM_CO_LOCALTEST flag is set in the call to lc_checkout Use lc_test_conf to retrieve information from a license file for tested features For checked out features use lc_auth_data The behavior of lc_test_conf is undefined if called in any other context other than after a tested feature 172 Advanced FLEXible API Features Advanced FLEXible API Functions The following code excerpt demonstrates using this function In this example the application obtains information for the feature just tested in order to display various fields For this example consider the following feature line from the license file FEATURE f1 demo 1 0 permanent 4 NOTICE ab SIGN XXXXXXXXXXXX The code appears as follows in the application VENDORCODE code LM_HANDLE 1m_job CONFIG conf lc_new_job 0 lc_new_job_arg2 code amp 1m_job Now perform the test checkout
193. ion 6 4 19 lc_perror FLEXible API 6 4 6 FLEXible API Function Descriptions Ic_errstring SYNTAX string lc_errstring job DESCRIPTION Returns the FLEX m error string for the most recent FLEX m error along with the major and minor error number If a UNIX error is involved the UNIX error description will also be included in the message along with the UNIX errno For internationalization of error messages use lc_err_info This memory is managed by the FLEX m library Do not attempt to free it This string is freed and reset when another FLEX m error occurs so it s only valid between calls to FLEX m functions Check that the call to the previous FLEX m function has returned an error before calling Ic_errstring PARAMETERS LM_HANDLE job From Ic_new_job RETURN char string The FLEX m error string text EXAMPLES No such feature exists 5 116 Cannot find license file 1 73 2 No such file or directory SEE ALso e Section 6 4 19 lc_perror e Section 6 4 5 lc_err_info FLEXIm Reference Manual August 2004 109 FLEXible API Function Descriptions 6 4 7 Ic_expire_days days lc_expire_days job conf DESCRIPTION Returns the number of days until a license expires PARAMETERS LM_HANDLE job From Ic_new_job CONFIG conf A FEATURE line from the license file If security is important and the FEATURE line information should be authenticated use Ic_auth_
194. ional START attribute for FEATURE INCREMENT UPGRADE lines This is the preferred method for a start date e For 20 character license keys embed the start date in the license key IMPLEMENTING LONG LICENSE KEYS AND EMBEDDED START DATES Here is how to turn on long license keys with embedded start dates in applications license generators and vendor daemons e In an application set long license keys with lc_set_attr job LM_A_LKEY_LONG LM_A_VAL_TYPE and embedded start dates with lc_set_attr job LM_A_LKEY_START_DATE LM_A_VAL_TYPE 1 300 Obsolete FLEXible API Features Obsolete License File Features e Make the same changes to the imcrypt c and makekey c sources in the machind directory of your FLEX m SDK e For the vendor daemon 1svendor c in machind directory set ls_a_lkey_long 1 long license keys ls_a_lkey_start_date 1 hidden start dates After these changes are made 20 character license keys with embedded dates are generated and 12 character license keys are not generated The start date is determined in one of three ways e To use the date the license is digitally signed use 0 for the license key field in the license line template Example FEATURE 2 demo 1 0 permanent uncounted 0 HOSTID 1234 To specify a start date other than the date the license is signed use start dd mmm yyy for the license key field in the l
195. isable the 1mdown command no user can run 1mdown If 1mdown is disabled you will need to stop lmgrd via kill pid UNIX or stop the imgrd and vendor daemon processes through the Windows Task Manager or Windows service On UNIX be sure the ki11 command does not have a 9 argument v4 0 Imgra x lmremove Disable the Imremove command no user can run lmremove v4 0 lmgra z Run in foreground The default behavior is to run in the background If 1 debug_log_path is present then no windows are used but if no 1 argument specified separate windows are used for Imgrd and each vendor daemon v Displays Imgra version number and copyright and exits 204 The License Manager Daemon Note License Server Configuration help Displays usage information and exits The license file list can also be specified by setting the environment variable LM_LICENSE_FILE to the file s path name The c path specification will override the setting of LM_LICENSE_FILE 10 1 1 Starting Imgrd on UNIX Platforms On UNIX systems it is recommended that 1mgrd be run as a non privileged user not root 10 1 2 Starting Imgrd on Windows Platforms 10 2 lmgrd can be started as an application from a Windows command shell For example C flexlm gt lmgrd c vendor lic The problem with running a server this way is that 1t occupies a window on the screen and may be difficult to start and stop On Window
196. ist of all license files searched for features Useful for failure messages for debugging For example include lm_attr h AA char ep lc_get_attr job LM_A_LF_LIST short 8cp if cp puts files searched are while cp printf t s n short cp 7 3 10 LM_A_LICENSE_DEFAULT 144 Type char Controlling Licensing Behavior Note 7 3 11 FLEXible API Attributes set by Ic_set_attr It is strongly recommended that this attribute be set in all licensed applications The expected location of the application s license file directory This is a directory that contains one or more license files with a lic extension This location can be hardcoded at compile time or determined dynamically at run time However it is recommended to determine this location dynamically at run time See the FLEXIm Programmers Guide for more information on how this location is used by the licensed application If LM_A_LICENSE DEFAULT is set FLEX m still honors the VENDOR_LICENSE_FILE and LM_LICENSE_FILE environment variables and or the license finder first LM_A_LICENSE_FMT_VER Type char Default LM_BEHAVIOR_V8 Licenses generated by Ic_cryptstr will be compatible with the version specified Valid arguments are LM_BEHAVIOR_V x where x is 2 3 4 5 5_1 6 7 7_1 8 8_1 8_2 8_3 or 9_0 Ifthe license compatible with the desired version cannot be generated The error LM_L
197. isting job previously initialized with Ic_new_job lc_new_job_arg2 This second parameter is required for enhanced security for a DLL RETURN pointer to Pointer to VENDORCODE struct VENDORCODE code Initialized by this function and used later as argument to Ic_checkout pointer to Set to job for the current process This is LM_HANDLE job used as the first argument to all subsequent Ic_xxx functions int status Value of Ic_get_errno after initialization is complete 0 if successful ERROR RETURNS LM_BAD_TZ Time zone offset from GMT is gt 24 hours may imply a user is attempting to bypass an expiration date LM_BADPLATFORM Vendor keys do not support this platform LM_BADKEYDATA Bad vendor keys LM_BADVENDORDATA Unknown vendor key type LM_CANTMALLOC The call to malloc failed FLEXIm Reference Manual August 2004 127 FLEXible API Function Descriptions LM_DEFAULT_SEEDS Encryption seeds were left to default values but the vendor daemon name is not demo LM_EXPIRED_KEYS Vendor keys have expired LM_NOKEYDATA Vendor key data not supplied LM_LIBRARYMISMATCH Imclient h liblmgr a version mismatch LM_NONETWORK Networking software not available on this machine LM_OLDVENDORDATA Old vendor keys supplied SEE ALSO e Section 6 4 15 Ic_init e Section 6 4 10 Ic_free_job e Section 11 4 Multiple Jobs 6 4 18 Ic_next_job 128 SYNTAX L
198. k out two features P_HANDLE lp_handlel P_HANDLE lp_handle2 lp_checkout LPCODE LM_RESTRICTIVE f1 1 0 1 a b c license lic 1p_handlel lp_checkout LPCODE LM_RESTRICTIVE f2 1 0 1 a b c license lic amp lp_handle2 Ip_errstring SYNTAX string lp_errstring lp_handle DESCRIPTION Returns a string describing the previous FLEX m error PARAMETER LP_HANDLE lp_handie The handle from the lp_checkout call RETURN char string Error description FLEXIm Reference Manual August 2004 77 Simple API Function Descriptions 5 2 4 78 Ip_heartbeat SYNTAX status lp_heartbeat lp_handle num_reconnects num minutes DESCRIPTION Ip_heartbeat sends heartbeat messages to and receives acknowledgments from the license server By default these activities are handled automatically by FLEX m via a separate dedicated application thread See Section 12 1 Automatic Heartbeats for more details on automatic heartbeat messages This function provides manual control of heartbeat messages thereby overriding the automatic mechanism To use Ip_heartbeat you must first turn off the automatic mechanism by setting the LM_MANUAL_HEARTBEAT policy modifier in the Ip_checkout call If the license server goes down and later comes back up Ip_heartbeat automatically reconnects and checks the license out On failure it returns the
199. k_key to provide a user friendly front end Ic_convert also changes this_host in the SERVER line to the real host name in either decimal or readable licenses It does this only if Ic_convert is run on the same hostid as appears on the SERVER line and does not do this for hostids of DEMO or ANY If readable output is requested the output will be compatible with the LM_A_LICENSE_FMT_VER setting which defaults to the current FLEX m version Advanced FLEXible API Features Advanced FLEXible API Functions PARAMETERS LM_HANDLE job From Ic_new_job char str License file in readable or decimal format as a string pointer to str converted to desired format Should char return_str be freed by caller use lc_free_mem on Windows pointer to If return value is non zero then this is char errors set to a description of the problem Should be freed by caller use Ic_free_mem on Windows int flag LC_CONVERT_TO_READABLE or LC_CONVERT_TO_DECIMAL defined in Imclient h RETURN int status 0 success 1 if syntax error in str and errors is set to explanatory message Otherwise FLEX m errno ERROR RETURNS LM_BADPARAM Invalid flag argument SEE ALSO e examples advanced exinstal c for an example program e Section 8 1 10 Ic_next_conf e Section 8 1 5 lc_convert e Section 6 4 8 lc_feat_list FLEXIm Reference Manual August 2004 163 Advanced FLEXible API Functions
200. l August 2004 A 3 1 Data Types for All Calls oo o ooooooo oo 267 Ad LSAP General Calls td IS 267 Appendix B FLEXIm Parameter Limits 0 00 00 ooo 271 B 1 FLEX m Parameter General Information 271 B 1 1 Internationalization Support 005 271 B 1 2 Path Name Formats 0 0 00 c cece nee 271 B 2 Eicense File Mimittss 5 c g tes chee 8 bed a 272 B 3 Decimal Format License Limits oooooooo oo o 273 B 4 End User Options File Limits 0 2 0000005 273 B S JevsetattrQ limits a es eed a 274 B 6 Other API Teamits ba a a Spe dena eo ge 274 B 7 Vendor Daemon Limits 0 0 00 ccc cee ee eee 274 B S lmerd Limits 620 bea oes a a hea OY Eee ae 275 B 9 Subnet Domain Wide Area Network Limits 275 B 10 LM_LICENSE_FILE VENDOR_LICENSE_FILE 275 Appendix C FLEX m Status Return Values 2 0 0 0 cee ee eee eee 277 C 1 Error Number Table oooooooooo oo 277 Appendix D Obsolete FLEXible API Features 0 0 0 0008 295 D 1 Obsolete FLEXible API Functions 00005 295 D 2 Obsolete FLEXible API Attributes o ooooo o o 298 D 3 Obsolete Vendor Daemon Variables 299 D 4 Obsolete License File Features oooooooooooo 299 D 4 1 License Key Length and Start Date
201. l converts the decimal lines to readable format lminstall does not however know where your application expects to find the license file You will need to make the license file location clear to the end user Refer to the FLEXIm End Users Guide for more information on lminstall FLEXIm Reference Manual August 2004 61 Decimal Format Licenses 3 8 1 3 8 2 62 Decimal Format Limitations PACKAGE lines cannot be represented in decimal format These can be shipped separately shipped in the license file in readable format or preferably pre installed as part of the normal application installation PACKAGE lines are not available in decimal format because they would be excessively long because they consist mostly of component names FEATURESET lines also cannot be represented in decimal format Very long FEATURE lines will be extremely long in decimal format If a license is very long in the normal format say gt 100 characters 1t could be up to three times longer in decimal format defeating the purpose of the format 69 Feature names that include cannot be represented in decimal format This is unsupported by FLEX m although some companies have used it Example Decimal Licenses COUNTED LICENSE SERVER this_host 12345678 VENDOR demo E E EATURE 0 demo 1 0 permanent 1 SIGN A7F6DFD8C65E EATURE f1 demo 1 0 permanent 1 SIGN AA8BD581EE65 Decimal format dem
202. l subsequent checkouts for features from this vendor will automatically use the license that worked previously Note that this location is added to all other locations the application may look for the license This automatic registry update can be turned off with lc_set_attr job LM_A_CKOUT_INSTALL_LIC LM_A VAL TYPE O0 RETURN int status ERROR RETURNS LM_BADCODE LM_BADHANDSHAKE LM_BADPARAM FLEXible API 0 OK license checked out lt gt 0O Error Signature in license file does not match other data in file Authentication handshake with daemon failed FLEX m function argument is invalid or there is an invalid setting in 1m_code h LM_BADSYSDATE LM_BAD_VERSION LM_BORROW_TOOLONG LM_BUSYNEWSERV LM_CANTCONNECT LM_FEATQUEUE LM_FUNCNOTAVAIL LM_LOCALFILTER LM_MAXLIMIT LM_MAXUSERS LM_NO_SERVER_IN_FIL E LM_NOBORROW_SUPP LM_NOFEATURE FLEXible API Function Descriptions System clock has been set back This error can only occur when the FEATURE line contains an expiration date Version argument is invalid floating point format Cannot borrow a license for that many hours The user has specified a borrow period longer than the license allows License server busy starting another copy of itself retry Cannot establish a connection with a license server Feature is queued Ic_status will indicate when it is available Vendor keys d
203. lay or GUI based products like a window system LM_DUP_VENDOR All requests with the same vendor defined data use the same license Useful for sharing licenses among otherwise unrelated processes If LM_DUP_VENDOR is used LM_A_CHECKOUT_DATA must be set LM_DUP_USER All requests from this user LM_DUP_HOST name on this host name use the same license 96 FLEXible API LM_DUP_USER LM_DUP_DISP LM_DUP_USER LM_DUP_HOST LM_DUP_DISP M_DUP_VENDOR LM_DUP_USER L LM_DUP_SITE RESERVE AND DUP_GROUP FLEXible API Function Descriptions All requests from this user name on this display use the same license One user displaying on a single node using several nodes to run the software All requests from this user name on this host name using this display use the same license All requests from this user name with the same vendor data use the same license If LM_DUP_VENDOR is used LM_A_CHECKOUT_DATA must be set All requests from any user on any node on any display with any vendor data use the same license site license There is an important interaction between RESERVE and the duplicate grouping mask A license reservation for an entity not contained in the duplicate grouping mask in the call to Ic_checkout e g a USER reservation when the duplicate grouping mask is set to LM_DUP_HOST LM_DUP_DISP can cause an interesting interaction at run time To understand why this is the case c
204. les void x_flexlm_newid id HOSTID id LM_VENDOR_HOSTID h memset amp h 0 sizeof h h label VENDEF_ID_LABEL h hostid_num VENDEF_ID_TYPE h case_sensitive 0 h get_vendor_id x_flexlm_gethostid if lc_set_attr lm_job LM_A_VENDOR_ID_DECLARE LM_A_VAL_TYPE amp h lc_perror lm_job LM_A_VENDOR_ID_DECLARE FAILED The VENDEF_ID assignment would not be needed in a real situation in which you had a function that returned your vendor defined hostid Close vendor_hostid c Open machind lsvendor c ina text editor At the beginning of the vendor initialization routine section add a line defining x_flexlm_newid and modify the initial value of 1s_user_init1 from 0 to x_flexlm_newid Vendor initialization routines void x_flexlm_newid void ls_user_initl x_flexlm_newid Open machind Ilmcrypt c ina text editor After the call to Ic_init add the following line x_flexlm_newid That section of the code should resemble if lc_init LM_HANDLE 0 VENDOR_NAME site_code amp lm_job lc_perror lm_job lc_init failed exit 1 x_flexlm_newid FLEXIm Reference Manual August 2004 243 Editing Source Files 6 Open machind makekey c in a text editor After the call to Ic_init add the following line x_flexlm_newid That section of the code should resemble if lc_init LM_HANDLE 0 VENDOR_NAME amp Site_code LM_HANDLE
205. license server machine definition 21 license usage billback 199 in report log 199 license definition 20 license file list and equivalent hostids 34 FLEXIm Reference Manual August 2004 309 definition 20 limits decimal license 273 domain 275 error message 274 lc_checkout requests 274 Ic_set_attr 274 license file 272 LM_LICENSE_FILE 275 Imgrd 275 options file 273 subnet 275 vendor daemon 274 vendor defined hostid 274 wide area network 275 lingering licenses and Imremove 291 overview 208 Linux platform notes 252 LM 281 LM_A_APP_DISABLE CACHE REA D 140 M_A_BEHAVIOR_VER 175 _A BORROW _EXPIRE 141 _A BORROW STAT 141 _A CHECK BADDATE 142 _A_CHECK_INTERVAL 142 _A CHECKOUT_DATA 176 _A CHECKOUTFILTER 179 and VENDOR_STRING 49 _A CHECKOUTFILTER_EX 179 _A CHECKOUTFILTERLAST_E X 180 _A CKOUT_INSTALL_LIC 143 _A CONN_TIMEOUT 298 _A CRYPT_CASE_SENSITIVE 182 cae es Ssseeg eels lt lt mS IZ LM_A_DIAGS_ENABLED 182 LM_A_DISABLE_ENV 182 LM_A_DISPLAY_OVERRIDE 183 LM_A_FLEXLOCK 143 LM_A_FLEXLOCK_INSTALL_ID 143 LM_A_HOST_OVERRIDE 184 LM_A_LF LIST 144 LM_A_LICENSE_CASE_SENSITIVE 184 LM_A_LICENSE_DEFAULT 144 LM_A_LICENSE_FMT_VER 145 and Ic_convert 162 and Ic_cryptstr 102 LM_A_LINGER 145 208 M_A_LKEY_LONG 184 298 _A_LKEY_START_DATE 184 298 _A_LONG_ERRMSG 146 _A_MAX_TIMEDIFF 298 _A_MT_HEARTBEAT 184 M_A_PERIODIC_CALL 185 _A_ _A_ _A_ ENE Z P SSSSS888 PERIODIC_COUNT 185 PERRO
206. lude The end user is not denied usage during peak usage periods within limits e The vendor can gain additional revenue over traditional floating usage schemes FLEXIm Reference Manual August 2004 199 Lenient Licensing Report Log and OVERDRAFT A customer can limit costs resulting from OVERDRAFT usage by including a MAX_OVERDRAFT line in the options file LIMITATIONS The report log file while ASCII so it can be easily emailed is not human readable In addition any modifications to the file are detected by SAMreport However this does not mean that no tampering is possible There are three conditions that must be considered e First the customer may simply lose a file either by accident or on purpose Files are ended when a license server stops and starts or when an lmreread is performed These sections can be lost without detecting a file modification although the fact that a time period is missing can be detected e Second a policy is needed for missing reporting periods One example policy is More than x hours per month of missing license usage entries terminates the licensing contract e Finally a similar policy will be needed for files that have been altered 9 2 2 OVERDRAFT Detection Applications may want to inform users when they re in an OVERDRAFT state This can be done with Ic_auth_data and Ic_get_attr LM_A_VD_FEATURE_INFO lc_auth_data gives the CONFIG struct for the lice
207. m the daemon within the timeout interval The connection was reset by the daemon usually because the daemon exited before the process attempted to read data cannot write data to license server The process could not write data to the daemon after the connection was established license server does not support this feature The feature has expired on the server or has not yet started or the version is greater than the highest supported version error in select system call The select system call failed license server busy no majority The license server is busy establishing a quorum of server nodes so that licensing can start This error is very rare and checkout should be retried if this occurs license file does not support this version The version requested is greater than the highest version supported in the license file FEATURE line feature checkin failure detected at license server The checkin request did not receive a good reply from the vendor daemon the license might still be considered in use 280 FLEXIm Status Return Values 23 LM_BUSYNEWSERV 24 LM_USERSQUEUED 25 LM_SERVLONGGONE 26 LM_TOOMANY 29 LM_CANTFINDETHER 30 LM_NOR 31 LM_TOO 32 EADLIC EARLY LM_NOSUCHATTR Error Number Table license server temporarily busy new server connecting The vendor daemon is in the
208. mer might want to choose In practice what this means is that you would need to build and test with every possible licensing system Industry Standard Licensing APIs LSAPI General Calls Note You cannot mix LSAPI calls with the native FLEX m API calls A 3 1 Data Types for All Calls LS_ULONG unsigned long LS_STATUS_CODE unsigned long LS_STR char LS_CHALLENGE structure LS_CHALLENGE_FLEXLM structure LS_HANDLE unsigned long LS_VOID void A 4 LSAPI General Calls LS_STATUS_CODE List providers of LSEnumProviders LS_ULONG Index licensing service LS_STR Buffer LS_STATUS_CODE Get message text LSGetMessage LS_HANDLE Handle from licensing LS_STATUS_CODE Value LS_STR system Buffer LS_ULONG BufferSize LS_STATUS_CODE LSQuery LS_HANDLE Query license E andle LS_ULONG Information information LS_VOID InfoBuffer LS_ULONG BufferSize LS_ULONG ActualBufferSize LS_STATUS_CODE Release license LSRelease LS_HANDLE Handle LS_ULONG TotUnitsConsumed LS_STR LogComment FLEXIm Reference Manual August 2004 267 LSAPI General Calls Note 268 LS_STATUS_CODE Update license LSUpdate LS_HANDLE Handle status LS_ULONG TotUnitsConsumed S_ULONG TotUnitsReserved LS_STR LogComment SS_CHALLENGE
209. mgrd Command Line Syntax 0 0 00 0 0 eee 203 10 1 1 Starting Imgrd on UNIX Platforms 205 10 1 2 Starting Imgrd on Windows Platforms 205 10 2 License Server Configuration 00020000 205 viii FLEXIm Reference Manual August 2004 Chapter 11 Advanced FLEX m Topics 0 0 0 eee ee eee 11 1 FLEX m Example Applications 0 00 00 o 11 2 Lingering Licenses mia sina inate ine ees 11 3 FLEX m and Multithreaded Applications 11 4 Multiple Jobs eee eee II S FLEXI OGK 2 Pd 2inen deis Saisie eaid ecto batt baat bess 11 6 Security and FLEXIm 0 cee 11 6 1 11 6 2 Counterfeit Resistant Option CRO 04 Using Imstrip for Additional Security Chapter 12 Heartbeats a ca nen neces Sea a eines een hace tae aca hake 12 1 Automatic Heartbeats 000000 12 1 1 Controlling Automatic Heartbeat Behavior 12 2 Manual Heartbeats 0 0 00 eee 12 2 1 12 2 2 Controlling Manual Heartbeat Behavior Manual Heartbeat Example 0 0 00 eee 12 3 License Server side Considerations 000005 Chapter13 Vendor Daemon 0 cece cee teens 13 1 Configuring Your Vendor Daemon 04 13 2 Vendor Variables caer eee he hee Wk dave 13 2 1 13 2 2 13 2 3 13 2 4 Jsa DEHAVIOL A VE
210. mpts that were required to re connect for this feature int Maximum number of retry attempts that total_attempts would be made int interval Interval in seconds between reconnection attempts FLEXIm Reference Manual August 2004 151 FLEXible API Attributes set by Ic_set_attr 7 3 21 Note 152 void user_data LM_A_USER_RECONNECT_DONE_EX only A pointer to vendor defined data set via the LM_A_VENDOR_CALLBACK_DATA attribute SEE ALSO e Section 7 3 19 LM A USER RECONNECT LM_A_USER_RECONNECT_EX e Section 8 2 17 LM_A_VENDOR_ CALLBACK DATA LM_A VD GENERIC _INFO LM_A VD FEATURE_INFO Type Pointer to LM_VD_GENERIC_INFO or pointer to LM_VD_FEATURE_INFO Both attributes get information from your vendor daemon LM_A_VD_GENERIC_INFO gets information which is not specific to a feature and which is mostly found in 1svendor c LM_A_VD_FEATURE_INFO gets information about a particular feature and provides an accurate count of licenses used users queued etc and works correctly when a license file has more than one FEATURE or INCREMENT line for the same feature name This will result in a LM_NOSERVSUPP error if the particular CONFIG struct has been merged with another CONFIG in the vendor daemon These attributes will only work on your vendor daemon If a request is made for a feature only served by a different vendor daemon then the LM_NOADMINAPTerror results A pointer
211. n 8 1 10 lc_next_conf Section 8 1 5 Ic_convert Section 6 4 8 Ic_feat_list Section 6 4 3 Ic_checkout FLEXIm Reference Manual August 2004 Signature is invalid license has been typed incorrectly or altered in some way License format is invalid and may be from 161 Advanced FLEXible API Functions 8 1 4 162 Ic_cleanup Windows only SYNTAX void lc_cleanup DESCRIPTION This function frees all allocated memory releases all handles and kills all threads that are created by FLEX m client library routines Ic_cleanup must be the last FLEX m client library routine that is called by your FLEXenabled application Do not call any other FLEX m client library routines after calling this routine SPECIAL CONSIDERATIONS This routine is required if e Your FLEXenabled application dynamically links to the FLEX m client library Call Ic_cleanup before the DLL is unmapped from the application s address space e You distribute your product as a DLL To ensure all FLEX m resources are properly cleaned up after your end user s application unmaps your FLEXenabled DLL make sure you call Ic_cleanup in the logical clean up point in your DLL Ic_convert SYNTAX status lc_convert job str return_str errors flag DESCRIPTION This is an API for companies that want to provide their own front end for installing license files lc_convert can be used in combination with Ic_chec
212. n order to connect to another server we would need another job El if 1c_checkout LM_DUP_NONE job1 2 1 0 1 LM_CO_NOWAIT code if lc_new_job jobl lc_new_job_arg2 amp code amp job2 FLEXIm Reference Manual August 2004 209 FLEXlock 11 5 210 error processing job2 0 else set_all_my_attr job2 Reset attributes if lc_checkout job2 f2 1 0 1 LM_CO_NOWAIT amp code LM _DUP_NONE error processing application code here lc_checkin job1 LM_CI_ALL FEATURES 0 lc_free_job jobl if job2 amp amp job2 job1 lc_checkin job2 LM_CI_ALL FEATURES 0 lc_free_job job2 If the application is managing many jobs you may want to free jobs with Ic_free_job to save memory When doing so make sure that you do not delete a job which still has a license checked out this can result in a core dump Jobs can be found and managed using Ic_first_job and Ic_next_job which are used to walk the list of jobs Attributes for jobs are set and retrieved with Ic_set_attr and Ic_get_attr SEE ALSO e Section 6 4 10 Ic_free_job e Section 6 4 11 Ic_get_attr e Section 6 4 17 Ic_new_job e Section 6 4 9 Ic_first_job e Section 6 4 20 Ic_set_attr FLEX ock FLEX ock is available only on Windows If you are using FLEX ock and the FLEXible API and want to c
213. n that performs license file installation Table 6 7 lists the API functions and attributes related to license file installation Table 6 7 License File Installation Function or Attribute Name Description Functions Ic_hostid Provides the hostid in string format Attributes LM_A_FLEXLOCK Turns on FLEX ock capability LM_A_FLEXLOCK_INSTALL_ID Tags the FLEX ock operation with a random number 6 2 7 License File Generation These functions and attributes are provided to the vendor who wishes to develop a proprietary license file generation utility Table 6 8 lists them Table 6 8 License File Generation Function or Attribute Name Description Functions Ic_cryptstr Generates a valid signatures for a license file Ic_init Creates a job handle for use by Ic_cryptstr Attributes LM_A_LICENSE_FMT_VER Specifies the version format of the license that Ic_cryptstr generates 88 FLEXible API 6 3 Commonly Used FLEXible API Functions Commonly Used FLEXible API Functions Table 6 9 gives lists the most commonly used FLEXible API functions Full descriptions for the FLEXible API functions are presented later on in this chapter Table 6 9 Commonly Used Functions Function Name Ic_auth_data Description Gets the license file line for a checked out feature Often used to display license information to the user Ic_checkin Returns a license of a
214. n this chapter use a composite hostid comprised of HOSTID_ETHER and HOSTID_USER Initializing a Composite Hostid in Your Application Use Ic_init_simple_composite to initialize the composite hostid in your application Place code like the following in your application include lmclient h LM_HANDLE job Set up the list of hostid types which comprise the composite hostid hostids must appear in the same order as those in hostid lists specified in other components if int hostid_list HOSTID_ETHER HOSTID_USER int num_ids 2 void main IE lc_new_job amp Job Register the composite hostid ret lc_init_simple_composite job hostid_list num_ids if ret 0 error processing Pts Ep Composite Hostids 14 4 Initializing a Composite Hostid in Your Vendor Daemon Now anytime FLEXlm refers to HOSTID_COMPOSITE during this job it will be calculated based on both HOSTID_ETHER and HOSTID_USER LE Invoke Ic_init_simple_composite right after the call to lc_new_job Checkout requests using licenses that specify the COMPOSITE hostid type succeed only if the hostid in the license matches exactly with that dynamically calculated on the machine on which the application is installed That means both composite hostid constituents HOSTID_ETHER and HOSTID_USER have to be defined and match that to which make up the hostid specified by the COMPOSITE keywor
215. n_timeout normal_hostid d n gi normal_hostid minimum_user_timeout d n gi minimum_user_timeout min_lmremove d n gi min_lmremove use_featset din gi use_featset dup_sel 0x x n gi dup_sel use_all_feature_lines d n gi use_all_feature_lines do_checkroot d n gi do_checkroot 153 FLEXible API Attributes set by Ic_set_attr printf show_vendor_def d n gi show_vendor_def first 0 x get specific feature info x fi feat conf if lc_get_attr job LM_A_VD_FEATURE_INFO short amp fi lc_perror job LM_A_VD_FEATURE_INFO else printf Anfeature s n conf gt feature printf code s n conf gt code printf rev d n fi rev printf timeout d n fi timeout printf linger d n fi linger printf res din fi res printf tot_lic_in use d n fi tot_lic_ in use printf float_in_use d n fi float_in use printf user_cnt d n fi user_cnt printf num_lic d n fi num_lic printf queue_cnt d n fi queue_cnt printf overdraft d n fi overdraft DETECTING OVERDRAFT FOR SUITES This is a special case for OVERDRAFT With suites when you check out a feature you also silently check out a token for the suite Both the suite and feature token may be in the OVERDRAFT state or only one or neither To detect suite overdraft the code must get the parent suite feature name and then check
216. ncounted HOSTID hostid3 In contrast for counted licenses consider the following the following FEATURE line that provides one license node locked to a hostid list The one license can be used at any one time on any one of the specified hostids FEATURE 0 1 HOSTID hostidl hostid2 hostid3 However providing the following three FEATURE lines each with one license node locked to one hostid provides three licenses FEATURE fO 1 HOSTID hostidl FEATURE 0 1 HOSTID hostid2 FEATURE f0 1 HOSTID hostid3 SEE ALSO e FLEXIm End Users Guide for information about platform specific and special hostids e Section 3 2 SERVER Lines The License File Syntax FEATURE INCREMENT Lines 3 5 11 ISSUED ISSUED dd mmm yyyy Optional field Date that the license was issued Can be used in conjunction with SUPERSEDE 3 5 12 ISSUER ISSUER Optional field Issuer of the license 3 5 13 MINIMUM MINIMUM n Optional field If in Ic_checkout num_lic num_licis less than n then the server will checkout n licenses 3 5 14 NOTICE NOTICES pare Y Optional field A field for intellectual property notices 3 5 15 OVERDRAFT OVERDRAFT n Optional field The OVERDRAFT policy allows you to specify a number of additional licenses which your end user will be allowed to use in addition to the licenses they have purchased This is useful if you wa
217. ng FLEX m v6 licenses with short keys can be shipped e New customers can receive licenses with short keys D 4 2 FEATURESET Line The use of FEATURESET is discouraged The FEATURESET line is required only if 1s_use_featset is set in lsvendor c FEATURESET vendor key where vendor Name of the vendor daemon used to serve at least some feature s in the file key License key for this FEATURESET line This license key encrypts the license keys of all FEATURE lines that this vendor daemon supports so that no FEATURE lines can be removed or added to this license file The FEATURESET line allows the vendor to bind together the entire list of FEATURE lines supported by one vendor daemon If a FEATURESET line is used then all the FEATURE lines must be present in the same order in the customer s license file This is used for example to insure that a customer uses a complete update as supplied without adding old FEATURE lines from the vendor SEE ALSO e Chapter 2 The License File Overview 302 Obsolete FLEXible API Features Obsolete License File Features D 4 3 Intel Pentium Ill Hostid HOSTID_INTEL Note REQUIREMENTS e Windows CPU hostid must be enabled In May 2000 Intel announced their intention to discontinue support for CPUID ENABLING THE CPU HOSTID On most systems this is enabled in the BIOS Setup which you usually enter by pressing the DEL key when the system is first booti
218. ng in floating point format e g 12345 123 If the license in the license file has the same version number or a higher version number the checkout will succeed Macrovision recommends that this version number be a license version level and not the application s version number This version number should only be changed when you want old licenses to no longer work with a new version of the software The number of licenses to check out Usually this number is 1 A location in your installation hierarchy which indicates the expected license file location This is a directory containing one or more license files with a lic extension If 0 this argument is unused See the FLEXIm Programmers Guide for more information on how this location is used by the licensed application This is the return handle and is used for subsequent calls that apply to this checkout e g lp_checkin Ip_errstring etc If Ip_checkout is called more than once separate lp_handle variables must be declared and used and the corresponding handle must be used with the other Ip_xxx Simple APD calls 5 2 3 Simple API Function Descriptions Upon success the path to the license file used is set in VENDOR_LICENSE_FILE in the registry on Windows HKEY_LOCAL_MACHINE Software FLEX1m License Manager and SHOME flex1mrc on UNIX RETURN int status 0 if successful otherwise the FLEX m error number To chec
219. ng up If this is unavailable it likely means that the system is not a Pentium III or higher HOSTID LENGTH The true CPUID is a 96 bit value in the format a E where the s are uppercase hexadecimal characters According to Intel all 96 bits 24 hex characters are required to achieve a nearly unique hostid It is likely however that using the last 16 or 8 hex characters are very nearly unique Therefore we recommend that unless absolute uniqueness is required the 32 bit format should normally be used so that the license file is shorter and more readable The 64 bit version is a compromise between the two The required length is determined by what s put in the license file So if you want to use 96 bit CPUID then that s what should go in the license CONVERTING FROM 96 BIT TO 32 BIT The 32 bit hostid is simply the last 9 characters from the 96 bit version Similarly the 64 bit is the last 19 characters Length Example 96 bit 1B34 A0E3 8 AFA 6199 9C93 2B2C 64 bit 8AFA 6199 9C93 2B2C 32 bit 9C93 2B2C FLEXIm Reference Manual August 2004 303 Obsolete License File Features 304 LMTOOLS AND LMHOSTID 1mhost id takes the following arguments cpu 32 bit hostid cpu32 32 bit hostid cpu64 64 bit hostid cpu96 96 bit hostid SECURITY ISSUES Where available the CPUID is the preferred hostid because it is likely to be the most secure hostid We have taken extra precautions in the applications and
220. nopsis Syntax rules common to all sections Server Information SERVER Lines Contains information about the machines running the license server imgrd VENDOR Line Contains information about the vendor daemon that runs on the license server machines USE_SERVER Line Forces the FLEX m enabled product to access servers in preceding SERVER lines for licenses Package Information PACKAGE Lines Provides a way to license a set of components into one package License Rights Information FLEXIm Reference Manual August 2004 31 General Syntax Issues Table 3 1 License File Sections Continued Section FEATURE INCREMENT Lines Synopsis Describes the licensed features available for the specified vendor s products UPGRADE Lines Creates a new version of the license thereby replacing the older one 3 1 General Syntax Issues 3 1 1 Comment Lines It is a convention that comment lines begin with the character However all lines not beginning with a license file keyword are ignored and are considered comment lines 3 1 2 Line Continuation Long lines are broken up by line the continuation character 1 The following line is an example of using the line continuation character SIGN 123456789012 32 The License File Syntax FEATURE f1 demo 1 0 permanent 5 HOSTID adfe2345 3 2 SERVER Lines SERV
221. nse that has been used for the call to lc_checkout and LM_A_VD_FEATURE_INFO returns that actual OVERDRAFT state in the server CONFIG conf outline of C source LM_HANDLE Job LM_VD_FEATURE_INFO fi if rc lco_new_job amp job return rc error if re 1c_checkout job feature return rc error if fi conf lc_auth_data job feature report error else if rc lce_get_attr job LM_A_VD_FEATURE_INFO short amp fi report this error else if fc lic_in_use gt fi lic_avail fi overdraft printf s Number of overdraft uses d n feature fi lic_in_ use fi lic_avail fi overdraft SEE ALSO e Section 3 5 FEATURE INCREMENT Lines e Section 7 3 21 LM_A_VD_GENERIC_INFO LM_A_VD_FEATURE_INFO 200 License Models 9 3 Mobile Licensing Mobile Licensing See the FLEXIm Programmers Guide for examples of licensing methods that will allow end users to use FLEX m licensed applications on computers not connected to a license server FLEXIm Reference Manual August 2004 201 Mobile Licensing 202 License Models The License Manager Daemon The purpose of the license manager daemon Imgrad is to e Start and maintain all the vendor daemons listed in the VENDOR lines of the license file e Refer application checkout or other requests to the correct vendor daemon 1mgrad is a standard component of FLEX m that neither requires
222. nses or draw grant available for at gt limited most two distinct u write paint unlimite cers or draw grant 3 u3 write paint denied Maximum number or draw of distinct users exceeded 58 The License File Syntax PACKAGE Lines A FIXED NUMBER OF USERS SHARING COMPONENTS In this variation licenses are granted to a fixed number of users at any one time Independently a fixed number of licenses are granted for each suite component at any one time PACKAGE office demo 1 0 COMPONENTS write paint draw OPTIONS SUITE SIGN 00504091605D FEATURE office demo 1 0 permanent 2 SUITE_DUP_GROUP U DUP_GROUP NONE SIGN DB5CC00101A7 This license file defines a package suite named of fice with three components write paint and draw Additionally the suite duplicate grouping criterion SUITE_DUP_GROUP U is defined to the user level the feature duplicate grouping criterion DUP_GROUP NONE is the default and is supplied in this example for clarity At most two distinct users can be granted licenses at any one time and at most two licenses can be granted for each suite component at any one time Once the licenses are consumed no further licenses are available for checkout This concept is illustrated in the following table License Requested Checkout User Result Explanation Feature Attempt 1 ul or u2 write granted Two write licenses available 2 ul or u2
223. nt to allow your customers to not be denied service when in a temporary overdraft state Usage above the licensed limit will be reported by the SAMreport reporting tool In addition you can determine if the user is in an overdraft condition by calling lc_get_attr job LM_A_VD_FEATURE_INFO The returned structure has at least three members of interest lic_in_use lic_avail and overdraft If lic_in_use gt lic_avail overdraft then you are in an overdraft state 3 5 16 PLATFORMS PLATFORMS platl1 platn Optional field This allows you to restrict usage to particular hardware platforms The platforms are defined with FLEX m platform names and are the same as used to license FLEX m itself sun4_u5 186_n3 etc The FLEX m Release Notes contain the currently supported platforms and their associated FLEX m platform names FLEXIm Reference Manual August 2004 45 FEATURE INCREMENT Lines Note that the platform name can be overridden with lc_set_attr job LM_A PLATFORM_OVERRIDE LM_A VAL TYPE str Note that the trailing digit in the FLEX m platform name is ignored and can be optionally left off in the name If the platform list differs in any way for two INCREMENT lines for the same feature name they are pooled and counted separately Examples FEATURE f1 PLATFORMS sun4_u5 INCREMENT 2 1 PLATFORMS i86_n hp700_u INCREMENT 2 1 PLATFORMS i86_n
224. ntinue warn or terminate FLEXIm Reference Manual August 2004 217 Automatic Heartbeats Deciding how the heartbeats occur and what action takes place when the license server is not running is an important part of incorporating FLEX m in an application On both Windows and UNIX automatic heartbeats are recommended and are automatically implemented as a separate thread in the licensed application Heartbeats can be automatic or manual The distinction being how the timing of heartbeat messages is managed and how reconnection attempts are recognized and handled Table 12 1 summarizes these distinctions Table 12 1 Heartbeat Summary Automatic Manual Heartbeats Heartbeats Control of heartbeat Control of heartbeat timing timing is transparent viaa is regulated by the frequency a dedicated thread created with which the application ne by FLEX m on behalf of invokes a particular the application function Reconnection to license Application detects Reconnection server is handled individual reconnection Manas m nt automatically and attempts to the license server anageme transparently and determines how to respond e Requires the application e No multi threaded be multi threaded requirement Considerations e A dedicated heartbeat e The application has total thread is automatically control of the timing of interrupted rather than the heartbeat messages application 12 1 Automatic Heartbeats 218 By d
225. number of days until a license expires Ic_feat_list Gets the list of all features in the license file Ic_first_job Locates the first job on the list of jobs Ic_free_job Frees the memory associated with a job Ic_get_attr Retrieves a FLEX m attribute Ic_heartbeat Exchanges heartbeat messages with the license server Ic_hostid Provides the hostid in string format Ic_idle Informs the license server when the licensed application is idle Ic_init Creates a job handle for use by Ic_cryptstr Ic_log Logs a message in the debug log file Ic_new_job Initializes FLEX m and creates a new job Ic_next_job Walks the list of jobs Ic_perror Prints a FLEX m error message Ic_set_attr Sets a FLEX m attribute Ic_status Returns the status of the requested feature Ic_userlist Provides a list of who is using a feature Ic_vsend Sends a message to the vendor daemon and returns a result string SEE ALSO e Section 8 1 Advanced FLEXible API Functions e Section D 1 Obsolete FLEXible API Functions FLEXible API 6 2 6 2 1 FLEXible API Functions by Category FLEXible API Functions by Category Incorporating the FLEXible API into your application involves adding calls to functions from several different categories In the following sections the API functions are divided into categories to help guide you
226. o f0 16641 00780 63392 5 7302 22216 00830 23011 18641 4 demo f1 16641 00780 35488 34267 28385 54 Note that the first decimal line includes the SERVER VENDOR information and the second and any subsequent lines are much shorter DEMO LICENSE FEATURE 2 demo 1 0 1 jun 2005 uncounted HOSTID DEMO SIGN 6E06CC47D2AB Decimal format demo 2 23169 24979 00024 12403 47718 23830 1 The License File Syntax Decimal Format Licenses 3 8 3 Format of a Decimal License 3 8 4 Note Decimal format licenses have a fixed format which is easy to recognize vendor feature HHtHHHH HH vendor Vendor daemon name feature Feature name HEHEH Groups of five decimal numbers 0 9 separated by a hyphen The last group may be less than five digits The line includes a checksum which can detect all single digit errors and most multi digit errors in lines that are typed incorrectly Hints on Using the Decimal Format There are some tricks that are used internally to make decimal lines shorter Knowledge of these can be useful when designing FEATURE lines TEXT IN OPTIONAL ATTRIBUTES Text in the optional feature attributes are normally three times longer in the decimal format than in the normal format For example VENDOR_STRING limit 3 would require about 21 characters in the decimal version There s a trick to making this shorter If the text portion is a decimal or hex number then
227. o not support this function Checkout request filtered by the vendor defined filter routine Checkout exceeds MAX specified in options file All licenses in use Applications usually need to test for both LM_MAXUSERS and LM_USERSQUEUED instead of only LM_MAXUSERS No license server specified for counted license License BORROW support not enabled but borrowing was requested by the user Cannot find feature in the license file FLEXIm Reference Manual August 2004 99 FLEXible API Function Descriptions Note 100 LM_NOSERVSUPP LM_OLDVER LM_PLATNOTLIC LM_SERVBUSY LM_USERSQUEUED Server has different license file than client client s license has feature but server s does not License file does not support a version this new This platform is not authorized by the license running on a platform not included in PLATFORMS list License server busy the request should be retried This is a rare occurrence Like LM_MAXUSERS but also indicates that there are already some users queued Applications usually need to test for both LM_MAXUSERS and LM_USERSQUEUED instead of only LM_MAXUSERS If you want a checkout to depend on information in the license file call Ic_set_attr LM_A_CHECKOUTFILTER LM_A_CHECKOUTFILTER_EX or LM_A CHECKOUTFILTERLAST_E X before the call to lc_checkout If you want to display information to the user from a license file line
228. ob RETURN None ERROR RETURNS LM_BADPARAM No such job SEE ALso e Section 6 4 15 Ic_init e Section 6 4 17 Ic_new_job e Section 6 4 20 Ic_set_attr e Section 8 1 4 lc_cleanupQ Windows only e Section 11 4 Multiple Jobs FLEXIm Reference Manual August 2004 113 FLEXible API Function Descriptions 6 4 11 Ic_get_attr SYNTAX include lm_attr h status lc_get_attr job attr value DESCRIPTION Retrieves a FLEX m attribute attr describes which attribute to retrieve and the value is a pointer to the value for the attribute See 1m_attr h for attr constants and value types Attribute descriptions can also be found in Section 7 3 FLEXible API Attributes set by lc_set_attr and Section 8 2 Advanced FLEXible API Attributes Types of char are handled a little differently than other types Types of int or short are declared and a pointer to the declared variable is passed as an argument Types of char are declared as char and the variable itself is passed PARAMETERS LM_HANDLE job From Ic_new_job int attr Which attribute to get RETURN short value Value of the attribute value must be a pointer to the correct attribute type and should be cast to a short Return value is set in value int status 0 OK lt gt 0 error ERROR RETURNS LM_NOSUCHATTR No such attribute exists 114 FLEXible API FLEXible API Function Descri
229. ob LM_CODE macro was not used to define the VENDORCODE argument for Ic_new_job See Imclient h and lmflex c for an example of how to use the LM_CODE macro FLEX1m include file library mismatch An attempt was made to create a licensed binary with mismatching source header files and 1ib1mgr a The source code version must match the linking libraries No licenses to borrow All licenses that were available to borrow have already been borrowed FLEXIm Status Return Values 68 LM_NOBORROWSUPP 69 LM_NOTONSERVER 71 LM_BAD_TZ 72 LM_OLDV 73 ENDORDATA LM_LOCALFILTER 74 LM_ENDPATH 75 LM_VMS_SETIMR_FAILED 76 LM_INTERNAL_ERROR Error Number Table License BORROW support not enabled The license or the application doesn t support license borrowing but borrowing was requested by a user FLOAT_OK can t run standalone on SERVER If the license server machine hostid is specified after FLOAT_OK only the floating license can be used to run the application on the license server machine Invalid TZ environment variable On some operating systems the end user can significantly change the date using the TZ environment variable This error detects this type of theft Old style vendor keys 3 word Im_init detected that an old LM_CODE macro was used Local checkout filter requested req
230. odifier in the checkout call 2 Invoke Ic_heartbeat for Trivial or Simple API use It_heartbeat HEARTBEAT or Ip_heartbeat at whatever interval is deemed appropriate You decide the timing mechanism used to control the interval The following is an example code sequence using the FLEXible API status lc_heartbeat lm_job amp num_reconnects num_minutes if status 0 Monitor status and num_reconnects take appropriate action The heartbeat routine returns the number of reconnects over a given time period and the state of the connection to the license server Monitor these return values and take appropriate action FLEXIm Reference Manual August 2004 221 Manual Heartbeats The heartbeat routine performs the following services on behalf of the application It attempts to read the acknowledgement from the previous heartbeat If there is no acknowledgement it makes one attempt to reconnect to the license server If there is acknowledgement it sends the next heartbeat message It returns with a status O if there was an acknowledgment or the number of unacknowledged heartbeats This number is incremented for each consecutive time a heartbeat was not acknowledged After the fifth default consecutive unacknowledged heartbeat 5 calls to the heartbeat routine it causes the application to exit via the standard exit system call with the error message Lost License cannot re connect UNI
231. of the functions that implements manual heartbeats and link in 1m_nomt o before 1ib1mgr a thereby disabling automatic multithreaded heartbeats 17 1 Macintosh OS X The FLEX m SDK on Macintosh OS X is accessed from the command line 17 2 Solaris The default Solaris TCP port delay of four minutes may cause problems when restarting a license server especially a license server that is using a hard coded port number for example each of the three server redundant servers rather than selecting from a set of default port numbers If you have a problem restarting license servers on Solaris a root user can reset the port delay to 2 4 seconds 2400 milliseconds As a long term solution we recommend that one of the following lines be put in a boot script because the port delay is reset every time the machine reboots Solaris 2 6 usr sbin ndd set dev tcp tcp_close_wait_interval 2400 Solaris 2 7 usr sbin ndd set dev tcp tcp_time_wait_interval 2400 FLEXIm Reference Manual August 2004 251 Hewlett Packard 17 3 17 4 17 5 252 Hewlett Packard The dev lan0 device must be readable to obtain an ethernet hostid The uname i hostid is preferable for this reason and because ethernet is not always present In v2 4 dev lan0 must have read and write permissions for everyone Ethernet and FDDI are known to be supported devices although earlier versions of HP UX had a bug with FDDI as hostid On RS 6000 Imgrd cann
232. ogram s environment variables If it does not find it it then looks into the registry in HKEY_LOCAL_MACHINE SOFTWARE FLEX1m License Manager env_var where env_var is the environment variable This is especially useful for setting the license file if not using the default using LM_LICENSE_FILE The FLEX m license manager 1mgrd exe and the vendor daemon can also use registry values when they are started as a SERVICE The values they use are in a sub key in the above FLEX m License Manager key The following code snippet taken from installs c shows how to create registry entries for the server programs next write registry entries Update the registry Try creating opening the registry key if RegOpenKeyEx HKEY_LOCAL MACHINE SOFTWARE 0 KEY_WRITE amp hcpl ERROR_SUCCESS HKEY happ DWORD dwDisp char new_name 120 sprintf new_name FLEX1m License Manager s Service_Name if RegCreateKeyEx hcpl new_name 0 REG_OPTION_NON_VOLATILE KEY_WRITE NULL amp happ amp dwDisp ERROR_SUCCESS RegSetValueEx happ Lmgrd 0 REG_SZ Lmgrd_Path strlen Lmgrd_Path RegSetValueEx happ LMGRD_LOG_FILE 0 REG_SZ Log_File_Path strlen Log_File_Path RegSetValueEx happ License 0 REG_SZ License_Path strlen License_Path RegSetValueEx happ Service 0 REG_SZ Service_Name strlen Service_Name Finished with keys RegCloseKey
233. ons 88 license file installation functions 88 overview 17 FLEXIm End User Manual xiv FLEXIm Java Programmers Guide xiv FLEXIm Programmers Guide xiv FLEXIm version compatibility 250 FLEXLM_DIAGNOSTICS 182 FLEXlock checking out a feature 210 checking out more than one feature 211 checking whether application uses 211 flock lib 103 FLOAT_OK 43 floating license definition 20 flock lib 103 format of license file 23 G gethostname and LM_A_HOST_OVERRIDE 184 H HEARTBEAT 69 heartbeats automatic 218 definition 20 how Ic_heartbeat works 117 host SERVER line 33 HOST_BASED 43 HOSTID 44 hostid CPUID 303 determining with Imhostid 25 different platforms 25 dongle 259 HOSTID_INTEL 303 Intel Pentium IHI 303 SERVER line 34 table of expected 25 vendor defined 235 241 HOSTID_COMPOSITE 122 HOSTID_DEFAULT 122 HOSTID_DISK_SERIAL_NUM 121 HOSTID_DISPLAY 122 HOSTID_ETHER 119 120 121 122 HOSTID_FLEXID6 121 HOSTID_FLEXID7 121 HOSTID_FLEXID8 121 HOSTID_HOSTNAME 122 HOSTID_INTEL hostid 303 HOSTID_INTERNET 122 HOSTID_LONG 119 120 122 HOSTID_STRING 120 122 HOSTID_USER 122 HOSTID_VENDOR 123 HP platform notes 252 I IBM platform notes 252 INCREMENT line 36 installs exe 205 261 Intel Pentium III hostid 303 INTERNET hostid on SERVER line 34 ISSUED 45 ISSUER 45 FLEXIm Reference Manual August 2004 307 J Java APL overview 17 L 1_n36_buf 126 1_new_hostid 158 and lc_free_hostid 164 lc_alarm
234. onsider the following example Your software groups duplicates based on USER and DISPLAY Your end user has a license file with a single license Your end user reserves this license for HOST nodea User joe on display displaya on HOST nodea checks out a license He gets the license since his HOST matches the reservation User joe on display displaya on HOST nodeb checks out a license He also gets a license since he is grouped with the first license as a duplicate FLEXIm Reference Manual August 2004 97 FLEXible API Function Descriptions 98 e The first user joe displaya nodea checks in his license At this point in the example the situation appears to be inconsistent The second user continues to hold the reservation which means that a user on nodeb is using a license reserved for nodea Once this second user checks in the license the reservation will return to the pool of reservations to be used by anyone on nodea FLEX m was designed to allow this potential temporary inconsistency rather than the alternative which is to have an unusable reservation REGISTRY AND HOME FLEXLMRC Environment variables can be taken either from the environment or from the registry on Windows or SHOME flexlmrc UNIX After a successful checkout the VENDOR_LICENSE_FILE variable is set for the location in the registry Windows or HOME flex1mrc UNIX This way al
235. or defined hostids 1 Make a copy of your FLEX m production SDK Follow these instructions using the files in the duplicate SDK 2 Copy examples vendor_hostid vendor_hostid ctothe machind directory FLEXIm Reference Manual August 2004 241 Editing Source Files 242 3 View the file and find the define statements See Imclient h for HOSTID and LM_VENDOR_HOSTID definitions include lmclient h include lm_attr h include string h extern LM_HANDLE lm_job This must be the current job This example returns only 1 hostid define VENDEF_ID_TYPE HOSTID_VENDOR 1 define VENDEF_ID_LABEL VDH define VENDEF_ID 12345678 x_flexlm_gethostid Callback to get vendor defined hostid Sorry about all the windows types for this function af HOSTID ifdef PC LM_CALLBACK_TYPE endif PC IMPORTANT NOTE This function MUST call 1_new_hostid for a hostid struct on each call If more than one hostid of a type is found then call 1_new_hostid for each A AA A x x_flexlm_gethostid idtype short idtype HOSTID h l_new_hostid memset h 0 sizeof HOSTID if idtype VENDEF_ID_TYPE h gt type VENDEF_ID_TYPE strncpy h gt id vendor VENDEF_ID MAX_HOSTID_LEN h gt id vendor MAX_HOSTID_LEN 0 return h return HOSTID NULL Vendor Defined Hostid Types and make into a list using the next field Editing Source Fi
236. or and warning processing Function Description It_errstring Returns a string describing the most recent error ERRSTRING Trivial API 4 2 4 2 1 4 2 2 Trivial API Descriptions Function Description It_perror Presents current error message to user PERROR It_pwarn Presents current warning message to user PWARN It_warning Returns a string describing the most recent warning WARNING Trivial API Descriptions It_checkin CHECKIN SYNTAX void 1t_checkin void CHECKIN DESCRIPTION Releases the license for the feature and frees memory associated with the checkout It_checkout CHECKOUT SYNTAX status lt_checkout policy feature version license_file_ list status CHECKOUT policy feature version license file list DESCRIPTION Acquires a license for a feature PARAMETERS int policy See Section 7 1 Trivial and Simple API License Policies Example LM_RESTRICTIVE char feature The feature name to check out FLEXIm Reference Manual August 2004 67 Trivial API Descriptions 68 char version char license _ file list The version of the feature to check out This is a string in floating point format e g 12345 123 If the license in the license file has the same version number or a higher version number the checkout will succeed Macrovision recommends that this version number be a license
237. or dynamically The macro based Trivial API consists of macros that call the Simple API The only required header file is lmpolicy h and no other macros or function calls are needed Macros are named with uppercase letters The Trivial API is divided into the following functional categories e License acquisition e Heartbeat management e Error and warning processing FLEXIm Reference Manual August 2004 65 Overview of the Trivial API Note 66 You cannot mix function based and macro based Trivial API calls nor Trivial API calls with any other API calls Programming examples using the Trivial API and instructions for building your licensed application are located in the FLEXIm Programmers Guide License Acquisition These are the basic functions which acquire and release a license They are required and constitute the minimum Trivial API implementation Function Description It_checkin Releases a license and frees all FLEX m memory CHECKIN It_checkout Acquires a license CHECKOUT Heartbeat Management This function is used for manual heartbeat implementations If automatic heartbeats are specified by the call to CHECKOUT O lc_checkout in the FLEX m enabled application this function is not explicitly used Function Description It_heartbeat Sends a heartbeat manually to the license server HEARTBEAT Error and Warning Processing These functions provide optional err
238. ors h and lm_lerrs h in the machind directory for English versions of the error messages int min_errno The minor error number This allows a support person with access to the FLEX m source code to pinpoint the location where the error occurred int sys_errno The most recent system errno or Winsock error on Windows char feature The name of the feature that the error applies to char lic_files A null terminated array of char pointers of the license files used when the error occurred FLEXIm Reference Manual August 2004 107 FLEXible API Function Descriptions 108 char context This is a string which gives additional information about the error Its contents depends on the type of error but is not language dependent Refer to machind lcontext h for information needed for translation This information allows applications to present error messages in any language and in any desired format The FLEX m SDK provides the English text of all messages The three types of messages that need to be translated are e short located in machind lmerrors h e long located in machind 1m_lerr h e context located in machind lcontext h Use the value err_info maj_errno as an index into these files in order to retrieve the corresponding message PARAMETERS LM_HANDLE job From Ic_new_job RETURN LM_ERR_INFO err_info Pointer to the LM_ERR_INFO struct outlined above SEE ALso e Sect
239. ot be started in etc rc because on that OS the TCP IP networking is started after etc rc is run IBM has recommended that this be performed in the etc inittab file Add a line like the following to etc inittab after the lines which start networking rclocal 2 wait etc rc local gt dev console 2 gt 41 IBM changed the system call that returns the node id uname several times most recently in AIX 3 1 the low order decimal digit of the machine serial number was left off The AIX 3003 version has a corrected system call which returns the entire serial number This means that the hostid of your customer s RS 6000 system can change when they upgrade OS revisions We know of no workaround other than to re issue licenses We believe that this condition stabilized in AIX v3 1 On UNIX automatic heartbeats are performed via multithreading by default on most UNIX platforms Applications on platforms that support pthreads must link in the pthreads library On AIX this is done by appending 1pthreads to the link line Linux If you are having difficulties building the FLEX m SDK on your Linux platform make sure that you have installed the correct platform specific FLEXIm file we provide three Red Hat Linux 5 2 or higher i86_g2 tar Red Hat Linux 6 2 or higher i86_r6 tar alpha_r6 tar Red Hat Linux 7 0 or higher it64_1r2 tar UNIX Platform Specific Notes SGI Macrovision has seen the following three types of problems with the
240. out 100 and lc_get_attr 115 and Ic_vsend 135 LM_NOSOCKET 7 278 and Ic_log 126 FLEXIm Reference Manual August 2004 313 LM_NOSUCHATTR 32 281 and lc_get_attr 114 and lc_set_attr 131 LM_NOT_THIS_HOST 95 290 LM_NOTLICADMIN 63 286 and lc_remove 171 and Ic_shutdown 172 LM_NOTONSERVER 69 287 LM_NOTTHISHOST 9 278 LM_OLDVENDORDATA 72 287 and Ic_init 125 and Ic_new_job 128 LM_OLDVER 21 280 and Ic_checkout 100 LM_PLATNOTLIC 89 289 and Ic_checkout 100 LM_POOL 93 290 LM_PUBKEY_ERROR 115 292 LM_QUEUE 138 LM_REMOVE_ LINGER 100 291 LM_REMOVETOOSOON 64 286 and Ic_remove 171 LM_RESTRICTIVE 137 LM_RESVFOROTHERS 101 291 LM_RETRY_RESTRICTIVE 139 LM_SELECTERR 19 280 LM_SERVBUSY 20 280 and lc_checkout 100 LM_SERVER_MAXED_OUT 106 292 LM_SERVER_REMOVED 92 290 LM_SERVLONGGONE 25 281 LM_SERVNOREADLIC 61 285 and Ic_get_config 165 LM_SERVOLDVER 83 288 LM_SETSOCKFAIL 58 285 LM_SIGN_REQ 114 292 LM_SOCKETFAIL 57 285 LM_TOOEARLY 281 LM_TOOMANY 26 281 M_TSOK_ERR 103 292 M_USE_FLEXLOCK 210 M_USER_BASED 83 289 M_USERSQUEUED 24 281 and Ic_checkout 100 M_VENDOR_DOWN 97 291 M_VER_BEHAVIOR and LM_A_LICENSE_CASE_ SENSITIVE 184 LM_VMS_SETIMR_FAILED 75 287 Imadmin group Ic_remove 170 Imclient c 207 Imdown disabling 204 262 Ic_shutdown 171 restricting access 204 Imflex c 207 Imgrd and LM_LICENSE_FI
241. peration of FLEX m when the connection to the server is lost is to try five times and then exit the program FLEX d Hardware Hostids Dongles A FLEXid is a parallel or USB dongle that is used to provide a hardware based moveable hostid FLEXids are manufactured for Macrovision and are purchased directly from Macrovision by vendors to sell to their customers A FLEXid hostid has the form FLEXID id_string where id_string indicates the FLEXid serial number Macrovision provides an installer that installs the appropriate OS drivers for all currently available FLEXids available in the plat form folder of the FLEX m SDK and are also available to vendors from http www globes com the Macrovision support web site Macrovision recommends that you provide the installer to your customer and with instructions to install all of the FLEXid drivers Consult FLEXid_README pdf in the machind directory for specific installation instructions SEE ALSO e Table 6 11 for complete FLEXid hostid support FLEXIm Reference Manual August 2004 259 FLEXIm Environment Variables 18 8 FLEX m Environment Variables Many aspects of FLEX m can be controlled using environment variables Environment variables can be set either in the traditional way or as an entry in the registry The FLEXIm End Users Guide contains a listing of all FLEX m environment variables A FLEX m component looks for an environment variable it first looks to the pr
242. perror SYNTAX void lp_perror lp_handle string DESCRIPTION Presents string and a description of the most recent error to the user On Windows this appears in a dialog PARAMETERS LP_HANDLE 1lp_handle The handle from the lp_checkout call char string A string describing the error context Ip_pwarn SYNTAX void lp_pwarn lp_handle string FLEXIm Reference Manual August 2004 79 Simple API Function Descriptions 5 2 7 80 DESCRIPTION Presents stringand a description of the most recent warning to the user On Windows this appears in a dialog on other systems it prints to stderr This is useful with policy set to LM_LENIENT or LM_FAILSAFE Nothing is printed if there is no warning PARAMETERS LP_HANDLE lp_handie The handle from the lp_checkout call char string A string describing the error context Ip_warning SYNTAX string lp_warning lp_handle DESCRIPTION Returns a string describing the last FLEX m warning PARAMETERS LP_HANDLE lp_handie The handle from the lp_checkout call RETURN char string An explanatory string This is useful with policy set to LM_LENIENT or LM_FAILSAFE Simple API FLEXible API This is the most powerful API available for license management As such it contains many options enabling considerable flexibility Where possible new licensed applications should use the Trivial or Simple APIs which are documented in Ch
243. process of establishing a quorum condition New requests from clients are deferred during this period This request should be retried users are queued for this feature This error is similar to MAXUSERS but supplies the additional information that there are other users in the queue for this feature license server does not support this version of this feature The version specified in the checkout request is greater than the highest version number the daemon supports request for more licenses than this feature supports A checkout request was made for more licenses than are available This request will never succeed cannot find ethernet device The ethernet device could not be located on this system cannot read license file The license file cannot be read errno EPERM or EACCES feature not yet available The feature is not enabled yet current date is before the feature start date No such attribute A call to Ic_get_attr or Ic_set_attr specified an unknown attribute code FLEXIm Reference Manual August 2004 281 Error Number Table 33 LM_BADHANDSHAKE 34 LM_CLOCKBAD 35 LM_F EATOQUEUE 3 6 LM_F 3 3 EATCORRUPT LM_F EATEXCLUDE 39 LM_F EATNOT INCLUDE Bad encryption handshake with daemon The client performs an encryption handshake operation with the daemon prior to any licensing operations
244. pted RETURN int status 0 if successful otherwise it returns the number of failed attempts to reconnect to the server SEE ALSO e Section 7 2 1 LM_MANUAL_HEARTBEAT e Section 7 2 2 LM_RETRY_RESTRICTIVE e Chapter 12 Heartbeats It_perror PERROR SYNTAX void 1t_perror string void PERROR string DESCRIPTION Presents string and a description of the most recent error to the user On Windows this appears in a dialog PARAMETERS char string A string describing the error context It_pwarn PWARN SYNTAX void lt_pwarn string void PWARN string DESCRIPTION Presents string and a description of the most recent warning to the user On Windows this appears in a dialog This is useful with policy set to LM_LENIENT or LM_FAILSAFE Nothing is printed if there is no warning Trivial API 4 2 7 Trivial API Descriptions PARAMETERS char string A string describing the error context It_warning WARNING SYNTAX string 1t_warning string WARNING DESCRIPTION Returns a string describing the last FLEX m warning RETURN char string An explanatory string This is useful with policy set to LM_LENIENT or LM_FAILSAFE FLEXIm Reference Manual August 2004 71 Trivial API Descriptions 72 Trivial API Simple API 5 1 Overview of Simple API Functions The Simple API can do nearly everything the FLEXible API can do Use this API if your applica
245. ptions LM_NOADMINAPI LM_A_VD_GENERIC_INFO or LM_A_VD_FEATURE_INFO only request was made to other company s vendor daemon LM_NOSERVSUPP LM_A_VD_GENERIC_INFO or LM_A_VD_FEATURE_INFO only pre v4 0 server does not support these requests SEE ALso e Section 6 4 20 Ic_set_attr e Section 7 3 FLEXible API Attributes set by lc_set_attr 6 4 12 Ic_heartbeat SYNTAX status l1lc_heartbeat job num_reconnects num minutes DESCRIPTION Ic_heartbeat sends heartbeat messages to and receives acknowledgments from the license server By default these activities are handled automatically by FLEX m via a separate dedicated application thread This function provides manual control of heartbeat messages thereby overriding the automatic mechanism The purpose of heartbeat messages is to e Keep license server informed that the application is still using its license otherwise the license server may timeout and check in the license e Keep the application informed that the license server is continually running unchecked license server stops and starts may indicate unauthorized license usage Ic_heartbeat performs the following activities e It attempts to read the acknowledgement from the previous heartbeat e It sends out a heartbeat message or if there is no acknowledgement from the previous one it makes one attempt to reconnect to the license server e If reconnection is successful re checks out t
246. r any security must be built into your code independent of the license server The complexity is exposed to you in the challenge mechanism which is a standard authentication technique known as handshaking If you are considering using LSAPI in your product you should read U S patent 5 375 206 issued to HP and understand its implications LSAPI has several significant drawbacks compared to the FLEX m APIs In addition Macrovision believes that the stated goal of license server independence cannot be met by the current version of the LSAPI spec see last point below Some of the drawbacks of LSAPI compared to the native FLEX m APIs are e Unreasonable error reporting only a total of 14 error codes e No ability for the vendor to support license queueing e No vendor specific checkout filtering e New hostid types are not definable by the software vendor e No provision to pass messages between the client and license server e No way to get license status without doing I O to the license server e No way to support a node locked license without a license server e No way to retrieve information about the licensing policy e No way to ship a vendor neutral license This means that in order to accomplish the stated goal of allowing your end user to select the licensing system from the vendor of their choice you would have to provide licenses in the format required by each and every license system which your custo
247. r_on_upgrade asset_info asset_info Optional field Additional information provided by the software end user s license administrator for asset management Not encrypted into the feature s signature dist_info dist_info Optional field Additional information provided by the software distributor Not encrypted into the feature s signature 3 5 27 sort sort nnn Optional field Used to override the default sorting order of FEATURE INCREMENT lines nnn specifies the relative sort order The default sort order value is 100 Lines with a sort order value of less than 100 are sorted before all lines without this attribute and lines with a sort order value greater than 100 appear after all unmarked lines All lines with the same number are sorted as they appear in the file Licenses are automatically sorted when they are processed by FLEX m the default sorting rules are is as follows 1 License file Automatic sorting does not occur across files in a license file list FLEXIm Reference Manual August 2004 49 UPGRADE Lines 3 5 28 3 5 29 3 6 50 Feature name FEATURE before INCREMENT Uncounted before counted Version lower versions before higher versions Nn Bu N Issued date in reverse order newest first The date is taken from ISSUED or START 7 Original order is otherwise maintained To turn off automatic ordering add sort nnn where nnn is the same on all lines A
248. range 27000 27009 License files per lmgrd process Unlimited Subnet Domain Wide Area Network Limits FLEX m has no limitations regarding subnets because FLEX m does not use broadcast messages If the host name in the license file is fully qualified name domain suf or is an IP address then there are no limitations with regard to Internet domains There are no other limitations regarding wide area networks B 10 LM_LICENSE_ FILE VENDOR_LICENSE_FILE Number of licenses in path Unlimited FLEXIm Reference Manual August 2004 275 LM_LICENSE_FILE VENDOR_LICENSE_FILE 276 FLEXIm Parameter Limits FLEX m Status Return Values C 1 Error Number Table These are all the possible errors returned from Ic_xxx functions Error Number 1 LM_NOCONFFILE 2 LM_BADFILE LM_NOSERVER LM_MAXUSERS LM_NOFEATURE Symbolic Name and Description cannot find license file The license file cannot be opened invalid license file syntax Feature name is gt MAX_FEATURE_LEN or daemon name is gt MAX_DAEMON_LEN or server name is gt MAX_SERVER_NAME or a feature specifies no hostid and of licenses is lt 0 cannot connect to a license server The daemon name specified in the license file FEATURE line does not match the vendor daemon name licensed number of users already reached The licensed number of users has been reached no such feat
249. ration date and the fact that it s a demo license node locked to HOSTID DEMO The product is fully usable until January 1 2005 FEATURE lines like this can be pre printed with different expiration dates and given to salespeople and distributors For example you may distribute the following file the examples assume a vendor daemon named corp to avoid confusion FEATURE FEATURE FEATURE FEATURE oe tl El El f1 corp corp corp corp here Oo OO Oo 1 jan 2005 1 feb 2005 1 mar 2005 1 apr 2005 uncounted HOSTID DEMO SIGN AB1CC0916A06 uncounted HOSTID DEMO SIGN ABDCCO116A06 uncounted HOSTID DEMO SIGN BBDCA0OD151ED uncounted HOSTID DEMO SIGN BBDCBOE155F1 FLEXIm Reference Manual August 2004 197 Demo Licensing 9 1 2 198 If the current date is February 1 2005 then the salesperson would give an evaluator the third line which expires in a month March 1 2005 The evaluator could simply save the FEATURE line in the license file where the product expects it and then the product will run for one month A PACKAGE line can be used to make this even easier for multiple features If a company ships features A through F the company can initialize the licenses with PACKAGE all corp 1 0 COMPONENTS A B C D E F SIGN B0A0F011B491 Then appending a single demo FEATURE line can enable all these features FEATURE all corp 1 0 1 Jjan 2005 uncounted HOSTID DEMO SIGN AB1CC0916A06 The FEATURE l
250. rectory containing one or more license files with a lic extension If 0 this argument is unused See the FLEXIm Programmers Guide for more information on how this location is used by the licensed application e Multiple checkout requests from the same process in the same license job will not result in additional licenses being checked out unless a new request specifies more licenses than were previously checked out That is two calls to Ilc_checkout 1 will result in only one license being checked out not two A second call to request two licenses would result in a total of two licenses e For improved security it is recommended that the parameters feature version etc be hidden the string should not be directly declared in source code It should be built up chars or smaller strings and then created via sprintf That way it is more difficult for users to change the license being checked out by altering the string in the binary PARAMETERS LM_HANDLE job From Ic_new_job char feature The ASCII feature name desired FLEXIm Reference Manual August 2004 93 FLEXible API Function Descriptions char version The version of the feature desired in floating point format maximum of ten characters e g 12345 123 or 123 456789 This value must be lt the version number in the license file for the checkout to succeed Letters are not allowed in versions For example v1 0 is ille
251. report all these errors independently and does so via the errors parameter The errors parameter is used for both errors and FLEXIm Reference Manual August 2004 105 FLEXible API Function Descriptions 106 warnings If there is an error Ic_cryptstr returns non zero and no signatures are generated in return_str If there are only warnings the return value from Ic_cryptstr is success 0 but errors is set to a warning message Here is an example of error reporting Input FEATURE f1 demo 1 a50 01 jan 2005 uncounted HOSTID 08002b32b161 SIGN 0 Error reported stdin line 1 Bad version number must be floating point number with no letters With this error no signature is generated and return_str will be the same as the input str FLEXible API 6 4 5 FLEXible API Function Descriptions SEE ALso Section 8 1 3 Ic_check_key Section 8 1 5 Ic_convert Section 6 4 11 Ic_get_attr Section 6 4 15 Ic_init Section 7 3 11 LM_A_LICENSE_FMT_VER machind lmcrypt c machind makekey c Ic_err_info SYNTAX err_info lc_err_info job DESCRIPTION Returns a pointer to a LM_ERR_INFO struct which contains all necessary information to present an error message to the user This is the supported m ethod for internationalization and localization of FLEX m error messages The format of LM_ERR_INFO is int maj_errno The FLEX m error number See lmerr
252. resources setsockopt failed The setsockopt call has failed This is likely due to an OS error message checksum failure Communications error messages between client and server are encrypted and checksummed for security and integrity The checksum will usually fail because of poor networking communications Cannot read license file from server This occurs when the license file via LM_LICENSE_FILE or Ic_set_attr LM_A_LICENSE_FILE LM_AL_VAL_TYPE path is incorrectly defined This only occurs in lmutil when LM_LICENSE_FILE is set to port host or host 285 Error Number Table 62 LM_NONETWORK 63 LM_NOTLICADMIN 64 LM_REMOVETOOSOON 65 LM_BADVENDORDATA 66 LM_LIBRARYMISMATCH 67 LM_NONETOBORROW Network software tcp ip not available This is reported on systems where this is detectable Some systems may have this problem but the error will not be reported as LM_NONETWORK system calls will simply fail Not a license administrator Various functions such as lc_remove and Ic_shutdown require that the user be an license administrator depending on how 1mgrd was started Imremove request too soon An Ic_remove request occurred but 1ls_min_lmremove defined in lsvendor c seconds have not elapsed since the license was checked out See Is_vendor Bad VENDORCODE struct passed to lc_new_j
253. ride the host name as derived from the UNIX gethostname system call This value cannot be changed for a job after the initial connection to the vendor daemon 8 2 10 LM_A LICENSE CASE SENSITIVE 8 2 11 184 Type int Default False If True the license file is case sensitive This should be set to True to generate license files compatible with older versions of FLEX m This attribute is automatically set to True if the LM_A_LICENSE_FMT_VER or LM_A_BEHAVIOR_VER attributes are set to LM_BEHAVIOR_V5_1 or less SEE ALSO e Section 13 2 3 Is_a_license_case_sensitive LM_A_MT_HEARTBEAT UNIX Only Type int Default True This flag applies to UNIX platforms only If True the automatic heartbeat mechanism is controlled via a dedicated thread in the FLEX m enabled application The platform must support pthreads in order to implement a dedicated thread for heartbeat messages If False automatic heartbeats are controlled in the application s main thread using the SIGALRM signal SEE ALSO e Chapter 12 Heartbeats Advanced FLEXible API Features Advanced FLEXible API Attributes 8 2 12 LM_A PERIODIC_CALL Type Pointer to a function returning int Return value not used Default No periodic call This function if specified will be called each LM_A_PERIODIC_ COUNT times that Ic_heartbeat is called lc_heartbeat is called directly or automatically depending on the value of LM_A_CHECK_INTERVAL SEE ALSO
254. ring 183 dist_info 49 domain limits 275 dongle 259 DUP_GROUP 42 dup_group 58 DISPLAY 96 HOST 96 USER 96 VENDOR 96 duplicate grouping and lingering licenses 208 and PACKAGE SUITE 55 58 and RESERVE 97 display 96 host 96 mask 97 none 96 site 97 suite 55 57 58 user 96 vendor 96 E embedded start date 300 error messages internationalization 107 limits 274 localization 107 ERRSTRINGO 69 example applications FLEXible API 207 Simple API 207 Trivial API 207 examples directory 208 exinstal c and lc_check_key 161 and Ic_convert 163 expiration date 42 F FEATURE line asset_info 49 authentication 24 BORROW 42 CAPACITY 195 COMPOSITE 235 dist_info 49 DUP_GROUP 42 expiration date 42 feature name 41 FLOAT_OK 43 HOST_BASED 43 HOSTID 44 ISSUED 45 ISSUER 45 license count 42 MINIMUM 45 NOTICE 45 OVERDRAFT 45 PLATFORMS 45 signature 46 SN 46 sort 49 START 47 SUITE_DUP_GROUP 47 SUPERSEDE 47 syntax 36 TS_OK 48 USER_BASED 48 user_info 50 vendor name 41 vendor_info 50 VENDOR_STRING 48 version 41 feature line definition 19 feature name 41 feature definition 19 FEATURESET 302 line 195 306 FLEXIm Reference Manual August 2004 FLEXible API checkin and checkout functions 83 error and warning reporting functions 87 example application 207 function summary 81 functions by category 83 heartbeat management functions 84 information functions 86 job handling functions 84 license file generation functi
255. rrow_in and 1s_borrow_out SEE ALSO e Section 8 3 1 Is_borrow_in e Section 8 3 3 Is_borrow_out 8 3 3 Is_borrow_out void 1s_borrow_out char borrowdata int datasize default_BorrowOut This callback function appends the record borrowdata to a borrow data cache The license server calls this function if set every time a license is borrowed or lingered By default this callback is defined with an internal implementation that uses an internally defined borrow data cache You can override the internal implementation with your own function that accesses your vendor defined cache Your implementation needs to e Open the vendor defined cache e Append the contents of borrowdata of size datasize e Close the vendor defined cache Note Do not attempt to free the borrowdata buffer itself It is allocated on the stack and will get popped on return from the callback This function is one of the borrow data cache management routines the others being 1s_borrow_in and 1s_borrow_init SEE ALso e Section 8 3 1 Is_borrow_in e Section 8 3 2 Is_borrow_init 190 Advanced FLEXible API Features 8 3 4 8 3 5 8 3 6 Advanced Vendor Variables Is_borrow_return_early int ls_borrow_return_early 0 This variable controls whether the license server allows a borrowed license to be returned before the borrow period is over This variable has two settings 0 Don t allow borrowed licens
256. rypt command is provided in the Software Development Kit package in machind 1mcrypt c This as well as the coding example below provide usage information for Ic_crypstr CODING EXAMPLE global include and variable info include lmprikey h include Imclient h include lm_code h include lmseeds h include lm_attr h LM_ HANDLE 1m_job LM_CODE code ENCRYPTION_SEED1 ENCRYPTION_SEED2 VENDOR_KEY1 VENDOR_KEY2 VENDOR_KEY3 VENDOR_KEY4 VENDOR_KEY5 C code char errors char return_str int flag LM_CRYPT_FORCE char filename myfile lic char str MAX_CONFIG_LINE 100 if maximum license is 100 lines A set up str variable with valid license syntax Fete License Generator initialization The LM_CODE_GEN_INIT is called once during license generator initialization Do not call this macro more than once during the execution of the license generator FLEXible API if lc_init 0 if return_str LINKING YOUR LICENSE GENERATOR UTILITY LM_CODE_GEN_INIT amp code VENDOR_NAME amp code present error Initialization complete For Windows platforms amp 1lm_job if lc_cryptstr lm_job str amp return_str amp code flag filename amp errors present error and if non null print it out return_str is the correct license file string FLEXible API Function Descriptions Once you have successfully compiled your
257. s Imgrd can be installed as a service to allow it to be started and stopped through a user interface and run in the background To get imgra to run as a service you need to install it Two methods are available e Using the GUI application LMTOOLS e Using the command line utility installs exe Both are located in the plat form directory of your SDK installation Using LMTOOLS to install Imgrd as a service is the recommended technique see the FLEXIm Programmers Guide If you prefer to use the installs utility see Section 18 9 Installing Imgrd as a Service Using installs License Server Configuration FLEX m supports e Single license server nodes e Redundancy via a license file list e Three server redundancy FLEXIm Reference Manual August 2004 205 License Server Configuration 206 If all the end user s data is on a single file server then there is no need for redundant servers and Macrovision recommends the use of a single server node for the FLEX m daemons If the end user s data is split among two or more server nodes and work is still possible when one of these nodes goes down or off the network then multiple server nodes can be employed In all cases an effort should be made to select stable systems as server nodes in other words do not pick systems that are frequently rebooted or shut down for one reason or another Multiple server nodes can be any supported server nodes it is not required
258. s match e PLATFORM fields match e DUP_GROUP fields match e FLOAT OK fields match e VENDOR_STRING fields match SEE ALSO e Section 3 5 24 VENDOR_STRING e Section 3 6 UPGRADE Lines Is_daemon_periodic void 1s_daemon_periodic 0 Vendor defined periodic call in daemon If you set the function pointer 1s_daemon_periodicin 1lsvendor c to one of your functions this function will be called approximately once per minute in the vendor daemon s main processing loop You must ensure that the o file for this routine is linked into your vendor daemon Is_incallback int ls_incallback 0 To install a vendor defined checkin callback routine initialize 1s_incallback with a pointer to your routine The checkin callback is called with no parameters and the return value is unused The checkin callback routine is called after the checkin is performed To obtain the parameters of the current checkin call use the Is_get_attr call described in Section 13 2 10 Is_outfilter FLEXIm Reference Manual August 2004 229 Vendor Variables 13 2 7 13 2 8 Is_infilter extern LM_HANDLE lm_job int ls_infilter 0 To install a vendor defined checkin filtering routine initialize 1s_infilter with a pointer to your routine The checkin filter is called with no parameters If it returns O the current checkin is aborted a return of 1 allows the current checkin to continue If the filter
259. s specified e For FEATURE lines in your license template HOSTID COMPOSITE composite_hostid e For SERVER lines in your license template COMPOSITE composite_hostid where composite_hostid is a value your end user provides to you via the lmcomposite utility described in Section 14 5 Creating a Composite Hostid Utility SEE ALSO e Section 3 2 SERVER Lines e Section 3 5 10 HOSTID Composite Hostids Vendor Defined Hostid Types 15 1 Overview You can use the FLEXible API to define your own hostid type If you would like to discuss whether or not vendor defined hostids are feasible for your application you can contact Technical Support The FLEX m SDK provides a sample C source file examples vendor_hostid vendor_hostid c in which a fixed vendor defined hostid is set up In this section you can use this file to run through a procedure for setting up a vendor defined hostid In a real situation you would not use a fixed vendor defined hostid but would define and call a function that returns the hostid that you want to use A vendor defined hostid can be used on a SERVER or FEATURE line of a license file 15 2 Editing Source Files You must define your hostid type for this example we are using vendor_hostid c then make sure that the vendor daemon FLEX m license generators and your client application can recognize and use your hostid type Only Imcrypt and makekey can generate licenses with vend
260. sary not normally needed 3 Build the FLEX m SDK using make UNIX or nmake Windows 13 2 Vendor Variables If you need to customize your vendor daemon you can edit the vendor variables in 1svendor c Usually this file should be left as is Most of the variables in this file appear for historic and compatibility reasons and should not be used except where required for compatibility This chapter provides information for the most popular vendor variables SEE ALso e Section 8 3 Advanced Vendor Variables e Section D 3 Obsolete Vendor Daemon Variables FLEXIm Reference Manual August 2004 227 Vendor Variables 13 2 1 Is a _behavior_ver char ls_a_behavior_ver 0 like LM_A BEHAVIOR_VER This can be set to LM_BEHAVIOR_ Vx where x is 2 3 4 5 5_1 6 7 7_1 8 8_1 8_2 8_3 or 9_0 The default 0 is LM_ BEHAVIOR CURRENT which is v9_0 in v9 5 SEE ALSO e Section 8 2 1 LM _A BEHAVIOR_VER 13 2 2 Is_a_check_baddate int ls_a_check_baddate 0 like LM_A CHECK_BADDATE If set to 1 and the license that would authorize a checkout is expiring a check is made to see if the system date has been set back If the failure is due to detection of system date tampering the checkout error will be LM_BADSYSDATE SEE ALSO e Section 7 2 3 LM_CHECK_BADDATE e Section 9 1 2 Limited Functionality Demos 13 2 3 Is_a_license_case_sensitive int ls_a_license_case
261. semi colon on Windows A license file list can be accepted in most places where a license file is appropriate When a directory is specified all files matching lic in that directory are automatically used as if specified as a list Optional 12 to 20 character hexadecimal license signature used to authenticate a license An imgrd and one or more vendor daemon processes License server refers to the processes not the computer on which they run License server machine imgrd Node locked license Options file Report log file Signature FLEXIm Terms and Definitions A computer system on which license server processes run The license server machine will host all site specific information regarding all floating feature usage Multiple license server machines used for three server redundancy can logically be considered the license server machine Also known as license server node The background process or license manager daemon that sends client processes to the correct vendor daemon on the correct machine The same license manager daemon process can be used by any application from any vendor because this daemon neither authenticates nor dispenses licenses lmgrd processes no user requests on its own but forwards these requests to a vendor daemon A license that can authorize use of an application running on a single specific machine as opposed to on a network Node locked licenses are usually but not n
262. served licenses the license server You use this value in FEATURE and SERVER lines that specify the COMPOSITE hostid type Provide a utility with code similar to the following include lmclient h LM_HANDLE job char buf MAX_CONFIG_LINE Set up the list of hostid types which comprise the composite hostid hostids must appear in the same order as those in hostid lists specified in other components By int hostid_list HOSTID_ETHER HOSTID_USER int num_ids 2 void main PES lc_new_job amp Job Register the composite hostid ret lc_init_simple_composite job hostid_list num_ids if ret 0 error processing PRO pcg BY Now call lc_hostid specifying HOSTID_COMPOSITE as the hostid type PE ret lc_hostid job HOSTID_COMPOSITE buf if ret 0 printf The FLEX1m Composite HostID of this machine is s n buf else lc_get_errno job FLEXIm Reference Manual August 2004 239 Providing a Composite Hostid License 14 6 240 lc_free_job job exit 0 For your convenience this code is provided in its full form in examples composite lmcomposite c Distribute this utility to your end user Providing a Composite Hostid License To take advantage of your composite hostid you need to issue licenses to your end user that include the COMPOSITE hostid type This hostid type can be used anywhere a hostid i
263. ses are borrowed When licenses are borrowed you must shut down a license server with the force option 121 FLOAT_OK license must have LM _FLOATOK_ONEHOSTID exactly one dongle hostid The hostid to which the FLOAT_OK feature is node locked must be a single dongle hostid not a list of dongle hostids 122 Unable to delete local borrow LM_BORROW_DELETE_ERR MED 123 Support for returning a LM BORROW_RETURN_EARLY borrowed licens arly is not ERR enabled This support is enabled in the vendor daemon via the 1s_borrow_early_return variable 124 Error returning borrowed LM_BORROW_RETURN_ license on server SERVER_ERR FLEXIm Reference Manual August 2004 293 Error Number Table 294 125 Error when trying to checkout LM_CANT_CHECKOUT_ just a PACKAGE BUNDLE JUST_PACKAGE 126 Composite Hostid not COMPOSITEID_ initialized INIT_ERR 127 An item needed for Composite LM_COMPOSITEID_ Hostid missing or invalid ITEM_ERR 128 Error borrowed license LM_BORROW_MATCH_ERR doesn t match any known server license FLEXIm Status Return Values Obsolete FLEXible API Features The functions attributes variables and features listed in this section are obsolete but are still provided in the SDK for backward compatibility Their functionality has been replaced with more current features where possible th
264. stid returns an error The FLEXIm End Users Guide contains a list of currently supported platforms and their default hostid type PARAMETERS LM_HANDLE From Ic_new_job job int id_type The requested hostid type See id_types listed in the table below For backward compatibility other choices exist in lmclient h but are not applicable in this version of FLEX m char buf A pointer to a char array of length MAX_CONFIG_LINE If successful the hostid string is returned here HOSTID TYPES There are two groups of hostid types those valid for a specific platform and those valid on all platforms Table 6 11 lists the valid hostid types for a specific platform Table 6 11 Hostid Types Operating FLEX m Supported Hostid Description System Platform Types id_type AIX All HOSTID_LONG 32 bit hostid Alpha OSF All HOSTID_ETHER Ethernet address FreeBSD All HOSTID_ETHER Ethernet address FLEXIm Reference Manual August 2004 119 FLEXible API Function Descriptions 120 Table 6 11 Hostid Types Continued Operating FLEX m Supported Hostid alas l Description System Platform Types id_type HP UX Non Itanium HOSTID_LONG 32 bit hostid Itanium HOSTID_ID_STRING String ID maximum length is MAX HOSTID_LEN IRIX All HOSTID_LONG 32 bit hostid Mac OS HOSTID_ETHER Ethernet address HOSTID_FLEXID9 FLEXID 9 All e Mfg Aladdin Knowledge Systems Device HASP
265. sts the attributes and the effect they have on automatic heartbeat behavior Table 12 2 Automatic Heartbeat Control Attribute Description Thread Management LM_A MT _ HEARTBEAT Determines whether a dedicated thread in the application is used to manage heartbeats Default is to use a dedicated thread UNIX platforms only Exchange Management FLEXIm Reference Manual August 2004 219 Automatic Heartbeats Table 12 2 Automatic Heartbeat Control Attribute Description LM_A CHECK_INTERVAL Used to set the interval at which heartbeats are exchanged Default is 120 seconds Reconnection Strategy LM_A_RETRY_COUNT Used to adjust the number of reconnect attempts If 1 the application retries forever Default is 5 attempts LM_A_RETRY_INTERVAL Used to adjust the interval between retry attempts Default interval is 60 seconds LM_A_USER_RECONNEC Sets a pre reconnection callback LM_A_USER_RECONNECT_EX to a vendor defined routine Default is no handler LM_A_USER_RECONNECT_DONE Sets a post reconnection callback LM_A_USER_RECONNECT_DONE_EX to a vendor defined routine Default is no handler Lost Server Recovery LM_A_USER_EXITCALL Sets a callback to a vendor LM_A_USER_EXITCALL_EX defined exit handler Default is for FLEX m to call exit system call on behalf of the application
266. ted to a specific license server system which may not have any count available for subsequent license requests Consider making this test in a separate job inter to From Ic_new_job ENDORCODE code nt dup_group Duplicate grouping mask for this feature Requests for licenses from duplicates can either be grouped or not grouped Grouping duplicates allows license requests from separate processes to use a single license if the process s USER HOST DISPLAY and or VENDOR_DEFINED field are the same Duplicate grouping is valid only with counted licenses FLEXIm Reference Manual August 2004 95 FLEXible API Function Descriptions The dup_group parameter allows you to select what to compare to constitute a group from the set USER HOST DISPLAY VENDOR Any of the four fields that are not set to compare will automatically match thus not setting any of the four fields yields a site license since all users on all hosts on all displays are the same as far as the comparison is concerned The following examples illustrate the use of the duplicate grouping capability Value Meaning LM_DUP_NONE Every process gets a new license LM_DUP_USER All requests from this user name share the same license LM_DUP_HOST All requests from this host name share the same licenses This is a floating node locked license LM_DUP_DISP All requests from this display share the same license Useful for disp
267. test version of 1mgra will always support any FLEX m license The end user has to find out which 1mgrd at their site is the latest version This can be done using lmgrd v to get the version If an earlier version of Imgrd is used than the vendor daemon then various errors may occur especially Vendor daemon can t talk to 1mgra invalid returned data from license server FLEX m Version Compatibility When an end user has licensed products that incorporate various versions of FLEX m care must be taken to insure that the correct versions of 1Imgra and the FLEX m utilities are used The rules about FLEX m version compatibility are summarized as Version of 1mut i1 LMTOOLS must be gt Version of Imgrd which must be gt Version of vendor daemon which must be gt Version of FLEX m licensed application which must be gt Version of license file format Except for the license file use 1mver to discover the version of all these components For the vendor daemon 1mgra and 1muti1 you can also use the v argument to print the version Debugging Hints UNIX Platform Specific Notes On UNIX automatic heartbeats are performed via multithreading by default on most UNIX platforms Applications on platforms that support pthreads must link in the pthreads library On all platforms that support pthreads this is done by appending 1pthread 1pthreads on AIX to the link line If an application cannot use the pthreads library call one
268. th name support for any given FLEX m component is limited to those formats supported by the particular operating system on which the FLEX m component resides License File Limits The limits on names for the major parameters employed in the FLEX m license file are Max number of VENDOR lines Vendor daemon name length Host name length Max number of FEATURE INCREMENT UPGRADE lines FEATURE INCREMENT UPGRADE PACKAGE line length FEATURE name length Version including date based version Latest expiration date License count in FEATURE INCREMENT UPGRADE PACKAGE lines Maximum total license count for a given feature accounting for all FEATURE and INCREMENT lines for that feature in the same license pool Number of users FLEXIm Parameter Limits Unlimited 10 bytes 64 bytes Unlimited 2048 bytes 30 bytes 10 characters in floating point format e g 123 4567 2 10 2005 12 31 dec 9999 but we recommend using permanent instead 1 through 2 147 483 647 2 147 483 647 1 through 2 147 483 647 B 3 Decimal Format License Limits B 4 OVERDRAFT n HOST_BASED n USER_BASED n MINIMUM n BORROW n VENDOR_STRING string Other optional FEATURE attributes e g NOTICE Max readable length that can be converted to decimal Types of licenses that can be converted to decimal Types of FEATURE names that can be converted to decimal End User Options File Limits The line
269. that they be the same architecture or operating system FLEX m supports two methods of redundancy redundancy via a license file list in the LM_LICENSE_FILE environment variable and a set of three redundant license servers See the FLEXIm Programmers Guide for more information on license servers and recommendations about configuring license server machines The License Manager Daemon Advanced FLEX m Topics Basic instructions for building your FLEX m SDK adding calls to the Simple or Trivial API into your application and building your application can be found in the FLEXIm Programmers Guide This chapter contains information about some advanced FLEX m features that can be implemented using the FLEXible API and about FLEX m security 11 1 FLEX m Example Applications On both UNIX and Windows the FLEX m SDK contains the source for an example FLEXible API client application program called Imflex c lmclient c1is a small standalone program using the macro based Trivial API and is a good place to start to learn how to integrate FLEX m with your application A function based Trivial API example is provided in ltclient c A Simple API example program Imsimple c is also available The source to these four example programs is in the machind directory For Windows systems the machind directory contains 1mwin c the source for an example GUI application 1mwin uses Microsoft Visual C to build a slightly more complicated m
270. the duplicate grouping bitmask For example if user A s application performs the following checkout request lc_set_attr lm_job LM_A CHECKOUT_DATA dupl lc_checkout lm_job f1 1 0 1 LM_DUP_VENDOR FLEXIm Reference Manual August 2004 177 Advanced FLEXible API Attributes Note 178 and user B s application makes a similar request lc_set_attr lm_job LM_A CHECKOUT_DATA dupl lc_checkout lm_job f1 1 0 1 LM_DUP_VENDOR then the two checkout requests are considered duplicates based on the vendor duplicate grouping criteria of dup1 and only one license is consumed Duplicate grouping criteria can also be expressed in the license file via the DUP_GROUP keyword on FEATURE INCREMENT lines See Section 3 5 7 DUP_GROUP for further details If a custom vendor duplicate grouping criteria is specified via either LM_DUP_VENDOR in the call to lc_checkout or DUP_GROUP on the FEATURE INCREMENT line LM_A_CHECKOUT_DATA must set a checkout data string USER VISIBILITY You have the option in your vendor daemon of allowing the LM_A_CHECKOUT_DATA string to be visible or not The daemon variable 1s_show_vendor_def controls whether the checkout data string is visible to your end users via lmstat or any utility which calls Ic_userlist If you are considering using this attribute we recommend that you contact Technical Support for guidance SEE ALSO e Section 6 4 3 Ic_checkout
271. the application requires FLEX m functionality not provided in the Trivial API use the Simple API For complete flexibility use the FLEXible API The Simple Trivial and FLEXible APIs are documented in this manual the Java API is documented in the FLEXIm Java Programmers Guide 1 1 1 Trivial and Simple APIs In the Trivial and Simple APIs a licensing policy is selected as an argument to the license request call The Simple API must be used instead of the Trivial API when e A single process needs to separately license sub functionality that is when two or more feature names may be checked out The checkout call needs to be able to check out more than one license of a feature FLEXIm Reference Manual August 2004 17 FLEXIm APIs 1 1 2 FLEXible API Most commonly the FLEXible API is required for e Asynchronous queuing especially in GUI based applications where queueing is required e To obtain a list of users of a given feature 1 1 3 Migrating to the FLEXible API If you need the functionality of the FLEXible API but have been using either the Simple or Trivial API it is not difficult to migrate The following changes will have to be made 1 Remove the include directive for Impolicy h and add include Imclient h include lm_attr h 2 Declare the following two variables LM_HANDLE job VENDORCODE code 3 Before the checkout call add lc_new_job 0 0 amp code amp job lc_set_attr job LM_A_LI
272. the application will still run The end user could use SAMreport to report on historical usage which will show when licensed use is exceeded Application users will never be denied usage Errors that normally make a checkout fail are available as warnings LM_LENIENT In this policy if all licenses are in use the checkout will return a failure status showing that all licenses are in use For any other error no error is returned This is another form of optional end user licensing where the user is not penalized if licensing is not set up or if an operational error occurs Errors that would normally make a checkout fail are available as warnings Trivial and Simple API Policy Modifiers These modifiers are binary ORed I with the main policies described in Section 7 1 Trivial and Simple API License Policies The following policy modifiers are available e LM_MANUAL_HEARTBEAT e LM_RETRY_RESTRICTIVE e LM_CHECK_BADDATE e LM_FLEXLOCK LM_MANUAL_HEARTBEAT If this policy modifier is not specified heartbeats via It_heartbeat HEARTBEAT or lp_heartbeat are automatically sent every 120 seconds from the application to the server Default automatic heartbeats are recommended Controlling Licensing Behavior 7 2 2 7 2 3 7 2 4 7 3 FLEXible API Attributes set by Ic_set_attr If you want to disable automatic heartbeats and call It_heartbeat HEARTBEAT or Ip_heartbeat directly use for example LM
273. the composite hostid value if lc_hostid job HOSTID_COMPOSITE buf error processing FLEXIm Reference Manual August 2004 167 Advanced FLEXible API Functions PARAMETERS LM_HANDLE job From Ic_new_job int hostid_list A pointer to an integer array of one or more simple hostid types to be included in the composite hostid See Section 6 4 13 Ic_hostid for a list of valid hostid types int num_ids The number of hostid types specified in hostid_list RETURN int status 0 Success 10 Failure FLEX m errno is returned ERROR RETURNS LM_COMPOSITEID_ Error initializing the composite hostid INIT_ERR LM_COMPOSITEID _ An item needed for composite hostid is ITEM_ERR missing or invalid SEE ALSO e Section 6 4 13 Ic_hostid e machind lmclient h 168 Advanced FLEXible API Features Advanced FLEXible API Functions 8 1 10 Ic_next_conf SYNTAX CONFIG pos 0 conf lc_next_conf job feature 8pos DESCRIPTION Returns the next line in the license file as a pointer to a CONFIG structure matching feature The search is started from pos where pos 0 indicates the first line lc_next_conf automatically updates pos so it is ready to retrieve the next feature line on a subsequent call Ic_next_conf does not authenticate FEATURE lines That is a user can type in a FEATURE line with an invalid signature and Ic_next_conf will still return it lc_get_confi
274. the given version of FLEX m Valid values are LM_BEHAVIOR_V x where x is 2 3 4 5 5_1 6 7 7_1 8 8_1 8_2 0r 8_3 SE E ALSO Section 13 2 1 ls_a_behavior_ver FLEXIm Reference Manual August 2004 175 Advanced FLEXible API Attributes 8 2 2 LM_A CHECKOUT DATA 176 Type char Default None The LM_A_CHECKOUT_DATA attribute allows you to set a checkout data string Itis used to label the next successful checked out feature or to qualify a feature check in request with the checkout data label The checkout data string is a character string with a maximum size of MAX_VENDOR_CHECKOUT_DATA bytes 32 bytes The default value is the NULL string Each unique value of LM_A_CHECKOUT_DATA represents a unique license group the NULL string can be one of those unique values Like all other attributes set this before the checkout or checkin request it takes effect for all subsequent calls to le_checkout or lc_checkin until it is changed There are two scenarios where a checkout data string defined via the LM_A_CHECKOUT_DATA attribute setting can be used e To force the license count to be accumulated incrementally across multiple checkouts in the same license job rather than as an aggregate e To create a custom duplicate grouping criteria These scenarios are described below INCREMENTAL LICENSE COUNT By default checkout requests for the same feature and version from the same license job have an aggregate a
275. through the implementation process Each category includes the API functions and related attributes that are used with the lc_set_attr and Ic_get_attr functions Full descriptions for the FLEXible API functions are presented later in this chapter and the attributes are described in Section 7 3 FLEXible API Attributes set by Ic_set_attr Checkin and Checkout The licensed application interfaces to FLEX m via a set of routines that request check out and release check in licenses of selected feature s Table 6 2 lists the API functions and attributes related to checking in and checking out a feature Table 6 2 Checkin and Checkout Function or Attribute Name Description Functions Ic_auth_data Gets the license file line for a checked out feature Ic_checkin Returns a license of a feature to the license pool Ic_checkout Requests a license of a feature Ic_status Returns the status of the requested feature Attributes LM_A_BORROW_EXPIRE Sets the date and time when a borrowed license expires LM_A_CHECK_BADDATE Checks system date on the client node LM_A_LICENSE_DEFAULT The expected license file location LM_A_LINGER Controls the license linger time FLEXIm Reference Manual August 2004 83 FLEXible API Functions by Category Table 6 2 Checkin and Checkout Continued Function or Attribute Name Description LM_A_PROMPT_FOR_FILE Prompts the user for a license f
276. tion for feature pre processing L M_A_CHECKOUTFILTERLAST_EX Defines a pointer to a checkout filter function for feature post processing L M_A_CRYPT_CASE_SENSITIVE Controls case sensitivity of license file authentication L M_A_DIAGS_ENABLED Controls the output of detailed diagnostic data Advanced FLEXible API Features Advanced FLEXible API Attributes Table 8 2 Advanced FLEXible API Attributes Continued L Attribute M_A_DISABLE_ENV Description Controls the use of the LM_LICENSE_FILE environment variable L M_A_DISPLAY_OVERRIDE Overrides the display name L M_A_HOST_OVERRIDE Overrides the host name L M_A_LICENSE_CASE_SENSITIVE Controls license file case sensitivity L M_A_MT_HEARTBEAT UNIX Only Controls the use of multi threaded heartbeats L M_A_PERIODIC_CALL Defines a pointer to a function to be called after the specified number of heartbeats L M_A_PERIODIC_COUNT Specifies the number of heartbeats between calls to function specified by LM_A_PERIODIC_CALL L M_A_PLATFORM_OVERRIDE Overrides the platform name L M_A_RETRY_CHECKOUT Controls checkout retries L M_A_USER_OVERRIDE Overrides the user name 8 2 1 LM_A BEHAVIOR_VER Type char De fault LM_BEHAVIOR_V8 This sets the behavior of the FLEX m enabled application to
277. tion requires checking out more than one feature name at a time or if you need to acquire more than one license for a feature This API requires that you include the 1mpolicy h header file The functions are divided into the following categories e License acquisition e Heartbeat management e Error and warning processing Note You cannot mix calls to Simple API functions with calls to any other API functions Programming examples using the Simple API and instructions for building your licensed application are located in the FLEXIm Programmers Guide 5 1 1 Checkin and Checkout Functions These are the basic functions which acquire and release a license They are required and constitute the minimum Simple API implementation Function Description Ip_checkin Releases a license and frees all FLEX m memory Ip_checkout Acquires a license FLEXIm Reference Manual August 2004 73 Simple API Function Descriptions 5 1 2 5 1 3 5 2 5 2 1 74 Heartbeat Function This function is used for manual heartbeat implementations If automatic heartbeats are employed in the client application this function is not explicitly called Function Description Ip_heartbeat Sends a manual heartbeat to the license server Error and Warning Processing Functions These functions provide optional error and warning processing They are not required in the minimal implementation Function
278. tionally identical to permanent but because the decimal format supports only permanent or 1 jan 0 3 mar 0 is unsupported Dates farther in the future require many decimals to represent Therefore 1 jan 9999 takes about 14 characters while permanent requires about 1 SEE ALso e Iminstall in the FLEXIm End Users Guide The License File Syntax Trivial API 4 1 Overview of the Trivial API The Trivial API provides a basic interface to the FLEX m client library routines It is differentiated from the other FLEX m APIs by exposing only scalar data types and requiring that only one feature can be checked out at a time from a single application This API is not thread safe because it internally passes context between calls to checkout heartbeat checkin and between error information warning functions and other internal functions This API is available in two formats e Function based Windows only This format is for applications that must invoke functions rather than C macros This implementation is available to applications that link the FLEXI m client library dynamically The function based Trivial API consists of functions that call the FLEXible API The only required header file is 1mpolicy h Function names start with the 1t_ prefix e Macro based This format is for applications that can invoke C macros This implementation is available to applications that link the FLEX m client library either statically
279. to int If null this argument is num_reconnects ignored If non null and the client has just successfully reconnected to the server the return value will be 0 success and num_reconnects is set to the number of times the client has reconnected in the last minutes If this is a large number it may indicate attempted theft FLEXible API FLEXible API Function Descriptions int num_minutes If 0 this argument is ignored If non zero it s used to detect when a server is being started and stopped many times in a short period which can indicate attempted theft The reporting period is set with num_minutes RETURN int status If non zero the license server is currently down and is the number of failed attempts to reconnect How LC_HEARTBEAT WORKS Ic_heartbeat sends a heartbeat message to the license server It then reads the acknowledgement from the previously sent heartbeat The first heartbeat is sent after the application first connects to the license server via lc_checkout In this manner there is normally no delay in Ic_heartbeat If lc_heartbeat is unable to read an acknowledgement from the license server it makes one attempt to reconnect to the license server according to the following parameters e Each subsequent call to lc_heartbeat makes one reconnection attempt for a total of five attempts default The LM_A_RETRY_COUNT attribute is used to override the total number of attempts e Calls to l
280. to lc_set_attr specified an invalid value for its attribute Ic_get_attr LM_A_MASTER called without connection already established to server No FLEX1lm key data supplied in lc_new_job call No FLEX m key data was supplied to the Ic_new_job call Some FLEX m functions will be disabled Invalid FLEXlm key data supplied Invalid FLEX m key data was supplied to the Ic_new_job call Some FLEX m functions will be disabled FLEXIm function not available in this version This FLEX m function is not available This could be a result of a BADKEYDATA NOKEYDATA or DEMOKIT return from Ic_new_job Clock setting check not available in daemon Ic_checkout returns this code when the CLOCK SETTING check between client and daemon is not supported in this daemon To disable the clock check Ic_set_attr LM_A_MAX_TIMEDIFF LM_A_VAL_TYPE 1 FLEXIm Reference Manual August 2004 283 Error Number Table 48 LM_BADPLATFORM 49 LM_DATE_TOOBIG 50 LM_EXPIREDKEYS SoL LM_NOFLEXLMINIT 52 LM_NOSERVRESP 52 LM_CHECKOUTFILTERED 54 LM_NOFEATSET FLEXIm platform not enabled The software is running on a platform which is not supported by the vendor keys you have purchased To purchase keys for additional platforms contact Macrovision Date too late for binary format The start date format in FLEX m licenses are
281. ttr FLEXIm Reference Manual August 2004 139 FLEXible API Attributes set by Ic_set_attr 7 3 1 140 The essential FLEXible API attribute which should be set by every FLEXible APT licensed application is LM_A_LICENSE_DEFAULT This attribute defines the default license file location The following attributes are often useful e Vendor defined Hostid LM_A_VENDOR_ID_DECLARE e Customized checkout LM_A_BORROW_EXPIRE e Information useful for error or informational reporting LM_A_BORROW_STAT LM_A_LF_LIST LM_A_VD_GENERIC_INFO LM_A_VD_FEATURE_INFO The attributes are described in the sections the follow with one attribute per section The first line of each section is the data type of the attribute All attribute definitions are in 1m_attr h The attributes are changed with Ic_set_attr and are queried with Ic_get_attr When using these attributes with lc_set_attr the argument must be of the correct type each attribute below lists its associated type and must then be cast to LM_A_VAL_TYPE When using them with Ic_get_attr the pointer argument should point to a value of the correct type noting that short and int are different in this case and must be cast toa short SEE ALSO e Section 8 2 Advanced FLEXible API Attributes e Section D 2 Obsolete FLEXible API Attributes LM_A_APP_DISABLE_CACHE_READ Type int Default 0 By default after a successful checkout the license file location
282. uest Request was denied by filter specified in Ic_set_attr LM_A_CHECKOUTFILTER LM_A_VAL_TYPE filter Attempt to read beyond the end of LF path An error occurred with the list of license files SYSSSETIMR call failed SYS SETIMR is used on VMS to time out certain FLEX m system calls Internal FLEXlm Error Please report to Macrovision Software FLEXIm Reference Manual August 2004 287 Error Number Table 77 LM_BAD_VERSION 78 LM_NOADMINAPI 82 LM_BADPKG 83 LM_SERVOLDVER Bad version number must be floating point number with no letters A line in the license file has an invalid version number Ic_checkout was called with an invalid version Character string FLEXadmin API functions not available An attempt to get information from another company s vendor daemon was made via lc_get_attr LM_A_VD_ This function call is only allowed for the vendor s own vendor daemon Invalid PACKAGE line in license file PACKAGE line missing or invalid COMPONENTS A COMPONENT has number of licenses set with OPTIONS SUITE A COMPONENT has number of licenses 0 Server FLEX1lm version older than client s Vendor daemon FLEX m version is older than the client s FLEX m version This is only supported with a v5 0 client 288 FLEXIm Status Return Values 84 LM_USER_BASED 85 LM_NOSERVCAP 87 LM
283. ure exists The feature could not be found in the license file FLEXIm Reference Manual August 2004 277 Error Number Table LM_NOSERVICE 7 LM_NOSOCKET 8 LM_BADCODE 9 LM_NOTTHISHOST 10 LM_LONGGON E 11 LM_BADDATE no TCP license servic xists This happens if a SERVER line does not specify a TCP port number and the TCP license service does not exist in etc services no socket connection to license manager server Ic_disconn was called after the process had been disconnected from the socket This error can also occur if an internal error happens within sndmsg or _rcvmsg encryption code in license file is inconsistent The code in a license file line does not match the other data in the license file This is usually the result of not building all the software components with the same encryption seeds Check makekey c lsvendor c and your application code carefully to insure that they are all built with the same encryption seeds invalid host The hostid specified in the license file does not match the node on which the software is running feature has expired The feature has expired i e today s date is after the expiration date in the license file invalid date format in license file The start or expiration date in the license file is invalid 278 FLEXIm Status Return Values 12 LM_BADCOMM 3 LM_NO_SERVER_IN_FILE
284. used for the feature is cached in the VENDOR_LICENSE_FILE variable in the registry Windows or HOME f1ex1mrc UNIX All subsequent checkouts for features from this vendor will read the cache first to determine the license file location Controlling Licensing Behavior 7 3 2 7 3 3 FLEXible API Attributes set by Ic_set_attr To disable reading the cache set this attribute to 1 Set this attribute immediately after the call to lc_new_job and before any other code in the application SEE ALSO e Registry and HOME flexlmrc e Section 7 3 6 LM_A_CKOUT_INSTALL_LIC LM_A BORROW_EXPIRE Type char Default None Date and optional time when a borrowed license expires If you want your end users to request license borrowing from within your application issue a license with the BORROW keyword on a feature line and write an interface in which the user specifies the end date and optionally time when the borrowed license will be returned Before the call to lc_checkout call lc_set_attr job LM_A BORROW_EXPIRE LM_A VAL TYPE datestring where datestringis the date and optionally time when the borrowed license expires provided by the user through the interface The date in datestringisin dd mmm yyyy hh mm format and the time is according to a 24 hour clock For example 13 dec 2005 15 00 All subsequent license checkouts in this job will attempt to borrow licenses SEE ALSO
285. utomatic ordering does not affect the order of features returned by Ic_feat_list user_info user_info Optional field Additional information provided by the software end user s license administrator Not encrypted into the feature s signature vendor_info vendor_info Optional field Additional information provided by the software vendor Not encrypted into the feature s signature UPGRADE Lines UPGRADE feature vendor from_feat_version to_feat_version exp_date num_lic options SIGN sign All the data is the same as for a FEATURE or INCREMENT line with the addition of the from_feat_version field An UPGRADE line removes up to the number of licenses specified by num_lic from any old version gt from_feat_version and creates a new version with that same number of licenses UPGRADE operates on preceding FEATURE or INCREMENT lines starting with the first one with the lowest version whose version number is gt from_feat_version and lt to_feat_version For example the two lines INCREMENT 1 demo 1 0 1 jan 2005 5 SIGN 9BFAC03164ED UPGRADE f1 demo 1 0 2 0 1 jan 2005 2 SIGN 1B9A30316207 result in 3 licenses of v1 0 of f1 and 2 licenses of v2 0 of f1 The License File Syntax UPGRADE Lines And the three lines INCREMENT f1 demo 1 0 1 jan 2005 5 SIGN 9BFACO3164ED INCREMENT f1 demo 2 0 l1 jan 2005 4 SIGN 8BF3fb031643 UPGRADE f1 demo 1 0 3 0 1 Jan 2005 2 SIGN 1B9A3
286. vendor daemons to make this hostid extra secure We do not believe that the CPUID length is important to security We have every reason to believe that a duplicate 32 bit or 64 bit hostid will be so rare as to be insignificant although only time will tell Obsolete FLEXible API Features Index HOME flexlmrc 98 140 A about this manual xiii advanced features 157 AIX 252 API industry standards 265 Java 17 LSAPI v1 1 266 Simple 17 Trivial 17 asset_info 49 automatic heartbeats 218 B billing for license usage 199 BORROW 42 C CAPACITY 195 checkin callback vendor defined 229 checkin filter vendor defined 230 CHECKIN 67 checkout filter vendor defined 231 CHECKOUT syntax 67 chroot and ls_do_checkroot 191 client application definition 19 commands xiv COMPONENTS 52 COMPOSITE 235 composite hostid 235 defining 236 definition 235 in vendor daemons 237 initializing 167 issuing the license 240 steps to create 235 conventions X1V counted license definition 19 Counterfeit Resistant Option 211 CPUID hostid 303 CRO 211 D daemon death automatic reconnection 149 detecting 142 daemon definition 19 debug log file definition 19 debugging application 247 decimal format license 61 decimal format lc_convert 162 default license server ports 34 defining a composite hostid 236 detecting OVERDRAFT usage 200 disabling Imdown 204 262 Imremove 204 262 FLEXIm Reference Manual August 2004 305 DisplaySt
287. ver this exchange assures each that the other is still alive and healthy By default heartbeats are sent and acknowledgments are received automatically by the FLEX m licensed application at a pre determined interval If the license server is shut down and restarted the heartbeat mechanism in the application automatically reconnects to the server and checks out the complement of licenses that is currently being used If your application does not send heartbeats to the license server the application cannot determine that the license server has been shut down and restarted If the license server is restarted without the application s knowledge current copies of the application continue running and a new full complement of licenses becomes available for the license server making license over usage possible Every time the license server receives a heartbeat it immediately sends an acknowledgement message back to the application This message doesn t get picked up by the application until it is time for the next heartbeat this latency is by default 120 seconds This means the FLEX m licensed application does not detect that the license server is down until the time has passed for two heartbeats to sent If the license server is shut down the next heartbeat succeeds because the acknowledgement processed is from the previous heartbeat If a heartbeat is not acknowledged by the license server the application can decide what action to take co
288. version level and not the applications version number This version number should only be changed when you want old licenses to no longer work with a new version of the software A location in your installation hierarchy which indicates the expected license file location This is a directory containing one or more license files with a 1ic extension If O this argument is unused See the FLEXIm Programmers Guide for more information on how this location is used by the licensed application Upon success the path to the license file used is set in VENDOR_LICENSE_FILE in the registry on Windows HKEY_LOCAL_MACHINE Software FLEX1m License Manager and SHOME flex1mrc on UNIX RETURN int status SEE ALso 0 if successful otherwise the FLEX m error number e Section 7 1 Trivial and Simple API License Policies e Section 7 2 Trivial and Simple API Policy Modifiers Trivial API 4 2 3 4 2 4 Trivial API Descriptions It_errstring ERRSTRING SYNTAX string lt_errstring string ERRSTRING DESCRIPTION Returns a string describing the last FLEX m error set RETURN char string An explanatory string It_heartbeat HEARTBEAT SYNTAX status 1t_heartbeat status HEARTBEAT DESCRIPTION It_heartbeat HEARTBEAT sends heartbeat messages to and receives acknowledgments from the license server By default these activities are handled
289. ws See the FLEXIm Programmers Guide and Section 11 5 FLEXlock in this manual for additional information on FLEX ock LM_A_FLEXLOCK_INSTALL_ID Type short Default Unused FLEXIm Reference Manual August 2004 143 FLEXible API Attributes set by Ic_set_attr 7 3 9 For additional security each time that your application is installed and the user activates the FLEX ock operation a random id number is generated This number can be used to identify work done with your application in this mode If this number is saved in the work and compared when accessing it you may be able to determine if your application has been re installed FLEXlock is available only on Windows You can obtain this number by calling long code_id lc_get_attr job LM_A_FLEXLOCK_INSTALL_ID short amp code_id After the FLEX ock operation is activated an entry is generated in the registry It is located at HKEY_CURRENT_USER Software Macrovision CorporationYFLEXlock A subkey for each feature is located inside the FLEX ock subkey and is a combination of the vendor name and the feature name If this subkey is deleted the program will act as if you had never activated the FLEX ock functionality Familiarity with the registry editor is necessary for testing FLEX ock enabled features See the FLEXIm Programmers Guide and Section 11 5 FLEXlock for additional information on FLEX ock LM_A LF LIST Type Pointer to char L
290. xample the application must pend on the call to Ic_checkout If the application needs to continue doing processing use LM_CO_QUEUE in the call to Ic_checkout Call Ic_status immediately after the call to lc_checkout and any other Ic_xxx function until the license is granted or denied This might be coded in the following manner status lc _ checkout LM_CO_ QUEUE switch status case 0 break got the license case LM_MAXUSERS case LM_USERSQUEUED case LM_FEATQUEUE printf Waiting for license while lc_status job feature processing break got the license default lc_perror job Checkout for license failed FLEXIm Reference Manual August 2004 131 FLEXible API Function Descriptions PARAMETERS LM_HANDLE job char feature RETURN int status ERROR RETURNS LM_CANTCONNECT LM_FEATQUEUE LM_NEVERCHECKOUT SEE ALso From Ic_new_job The feature name Status of this feature in this process lt 0 error 0 feature is checked out by this process Feature was checked out but lost connection to the daemon This process is in the queue for this feature Feature was never checked out by this process or was checked back in after a checkout e Section 6 4 3 Ic_checkout 132 FLEXible API FLEXible API Function Descriptions 6 4 22 Ic_userlist Note
291. y is no longer provided by FLEX m use functionality provided by the native operating system Ic_set_errno Sets the FLEX m errno See e Section 4 4 5 lc_err_info e Section 4 4 19 lc_perror e Section 6 1 6 Ic_get_errno lc_timer Exchanges heartbeat messages with the license server See e Section 6 4 12 Ic_heartbeat Ic_username Returns environment information about the current username This functionality is no longer provided by FLEX m use functionality provided by the native operating system FLEXIm Reference Manual August 2004 297 Obsolete FLEXible API Attributes D 2 Obsolete FLEXible API Attributes The following attributes are obsolete and exist only for compatibility with earlier FLEX m versions They should be used with care and questions are welcomed before their use Attribute LM_A_CONN_TIMEOUT Description Sets the timeout for connection to a vendor daemon See e Section 7 3 16 LM_A_RETRY_COUNT LM_A_RETRY_INTERVAL LM_A_LKEY_LONG Enables 64 bit license keys License keys are obsolete See e Section 3 5 17 SIGN LM_A_LKEY_START_DATE Enables embedded start dates in license keys License keys are obsolete See e Section 3 5 19 START LM_A_MAX_TIMEDIFF Tests difference in clock settings between the client and the server Now automatically performed when needed LM_A
292. ymbols 4 You then ship ofile 1lib to your customers knowing that the FLEX m symbol names as well as the vendor specified symbol names are not detectable in the resulting library file LINKING WITH A LIBRARY THAT ALREADY USES FLEXL You can protect against symbol name conflict among multiple FLEX m enabled licensing libraries by using 1mst rip on each individual licensing library This technique obfuscates the FLEX m symbol names locally to each library eliminating FLEX m symbol name conflict when two or more such libraries are linked into an application binary FLEXIm Reference Manual August 2004 215 Security and FLEXIm Follow the scenarios presented in Providing Additional Security for Licensing Libraries above Because the FLEX m symbols are altered the resulting object file or library can be linked with a library that already has references to FLEX m symbol names regardless of the FLEX m version Both coexist successfully 216 Advanced FLEXIm Topics Heartbeats The FLEX m license server uses a TCP IP port to communicate to the licensed application it can detect when a connection to the licensed application is gone and frees its licenses automatically However an application needs to communicate regularly with the license server to detect that the server is still running This communication is effected via heartbeats A heartbeat is a message initiated by the application and acknowledged by the license ser

FLEXlm Reference Manual

Contents

Download Pdf Manuals

Related Search

Related Contents