lmsgi  :  license_init,  license_chk_out,  license_chk_in,
       license_timer,     license_set_attr,      license_expdate,
       license_errstr,  license_status, license_free - SGI FLEXlm
       library


HEADER FILE

       #include <lmsgi.h>


DESCRIPTION

       This  manual  page  describes   the   SGI   interface   to
       liblmsgi.a,  the  SGI extension to Globetrotter Software's
       FLEXlm library.  This library supports the interfaces pro­
       vided by FLEXlm as well as the functions described here.

       The  SGI  interface  defines  a small set of functions for
       licensing your software using the FLEXlm, and consists  of
       the following calls:

            license_init
            license_chk_out
            license_chk_in
            license_timer
            license_set_attr
            license_expdate
            license_errstr
            license_status
            license_free
            get_job

       When  using any of the liblmsgi library functions you must
       include the following header  and  macro  in  your  source
       file:

               #include <lmsgi.h>

               LM_CODE(code, ENCRYPTION_CODE_1, ENCRYPTION_CODE_2,
                       VENDOR_KEY1, VENDOR_KEY2, VENDOR_KEY3,
                       VENDOR_KEY4, VENDOR_KEY5);

       The  -llmsgi  flag must be given to the C compiler to link
       programs which contain calls to FLEXlm functions.

               cc file.o -llmsgi


ENVIRONMENT

       The following environment variables will modify the behav­
       ior of applications licensed with this library.

       LM_LICENSE_FILE
              If  set,  specifies  the name of one or more FLEXlm
              license files.  Multiple files can be specified  by
              separating  them  with  a colon (:).  The specified
              files are checked first for FLEXlm licenses.

              If set,  specifies  the  name  of  a  license  file
              database.   A license file database is a file which
              contains a list of one or more FLEXlm license files
              and/or directories containing FLEXlm license files.

              If LM_LICENSE_DB is not defined the default license
              file database, /var/flexlm/licensefile.db, is used.

              The format of a license file database is  one  file
              or directory per line.  Comments are indicated by a
              pound sign '#' in the first  column  of  the  line.
              Blank  lines  are ignored.  Trailing and/or leading
              whitespace is not allowed on a line.

              Any directory listed in the file  is  searched  for
              filenames  matching  "*.dat".   Any subdirectory is
              also searched (recursively).  All file  names  must
              also end with the "*.dat" extension.

       If  no  license  files  have  been  defined  by either the
       LM_LICENSE_FILE or  LM_LICENSE_DB  environment  variables,
       the      default      FLEXlm      license      file     is
       /var/flexlm/license.dat.

       license_init - Initializes the FLEXlm library.


SYNOPSIS

       #include <lmsgi.h>

       int license_init (VENDORCODE* code, char *vendorname,
                         boolean_t heartbeat);


DESCRIPTION

       license_init() initializes the FLEXlm library and  creates
       a  license  job.   All  subsequent calls to license_init()
       create new license jobs.  Each license is independent.

       code   Use the global variable "code" which was defined by
              the LM_CODE macro (see above).

       vendorname
              The name of the vendor daemon to use.

       heartbeat
              This  is  B_FALSE  or  B_TRUE.   If B_FALSE, then a
              default heartbeat protocol is implemented.   FLEXlm
              will  generate a SIGALRM at every LM_A_CHECK_INTER­
              VAL.  This will make a call to license_timer().  If
              B_TRUE,  then  the SIGALRM is not generated, and it
              is up the application to call license_timer() peri­
              odically.


EXAMPLE

       /*
        * The following code initializes the FLEXlm library and
        * uses sgifd as the vendor daemon. If any errors are detected,
        * then display them.
        */

       if ( license_init (&code, "sgifd", B_FALSE) < 0 ) {
               printf ("Initialization error: %s\n", license_errstr());
       }


DIAGNOSTICS

       license_init()  returns  a  0 upon success or a value less
       than 0 if an error is  detected.   The  error  string  can
       viewed via license_errstr().

       license_chk_out - Attempts to check out a license.


SYNOPSIS

       #include <lmsgi.h>

       int license_chk_out(VENDORCODE *code, char *feature, char *version);


DESCRIPTION

       license_chk_out()  checks out one (or more) license(s) for
       the specified feature and, for counted licenses, keeps the
       daemon  up  to date on the status of the process using the
       license(s).

       code   Use the global variable "code" which was defined by
              the LM_CODE macro (see above).

       feature
              The ASCII feature name desired.

       version
              The  version  of  the  feature  desired in floating
              point format, 3 decimal  places  max.   This  value
              must be less than or equal to the version number in
              the license file for the check out to succeed.

       The default  behavior  of  this  library  when  a  license
       request  fails  is  to  print the standard SGI feature not
       found message and exit.  To override this behavior, appli­
       cations  should  set  the  attribute LMSGI_NO_SUCH_FEATURE
       using license_set_attr  to  register  their  own  callback
       before calling license_chk_out.


DIAGNOSTICS

       license_chk_out() returns a 0 upon success or a value less
       than 0 if an error is  detected.   The  error  string  can
       viewed via license_errstr().

       license_chk_in - Return a checked out license.


SYNOPSIS

       #include <lmsgi.h>

       int license_chk_in(char *feature, int keep_conn);


DESCRIPTION

       license_chk_in()  checks  in  the license of the specified
       feature  that  had  been  previously  checked   out   with
       license_chk_out().

       feature
              The feature (license) name to be checked in.

       keep_conn
              A  non-zero  means "Keep connection to server"; a 0
              means drop TCP connection.  A zero should always be
              used as the default.  Unused for UDP.

              Consult  the  FLEXlm  Programmer's  Guide  for more
              details.


EXAMPLE

       /*
        * The following code returns the license, dummy, back to the
        * server. If any errors are detected, then display them.
        */

       if ( license_chk_in ("dummy", 0) ) {
               printf ("Check in error: %s\n", license_errstr());
       }


DIAGNOSTICS

       license_chk_in() returns a 0 upon success or a value  less
       than  0  if  an  error  is detected.  The error string can
       viewed via license_errstr().

       license_timer - Verifies the  connection  to  the  license
       server.


SYNOPSIS

       #include <lmsgi.h>

       void license_timer();


DESCRIPTION

       Periodic calls to license_timer() should be throughout the
       user's application.  These  calls  are  important  because
       they verify that the license currently checked out to your
       application remains valid.  The  user  may  want  to  call
       license_timer() before important steps in the program (for
       example, before writing a file to disk).


EXAMPLE

       /*
        * application code
        */

       license_timer();

       /*
        * some more application code and then
        * verify connection before writing to disk
        */

       license_timer();

       /*
        * some more application code
        */

       license_set_attr  -   Used   to   set   different   FLEXlm
       attributes.


SYNOPSIS

       #include <lmsgi.h>

       int license_set_attr(int key, LM_A_VAL_TYPE value);


DESCRIPTION

       license_set_attr()   set  a  FLEXlm  attribute.   The  key
       describes which attribute to set and value  describes  the
       value for that attribute.  A description of the attributes
       can be found in  the  FLEXlm  Programmer's  Guide  or  the
       header file lm_attr.h.

       key    The FLEXlm attribute to set.

       value  Value  to  set the key to.  Values should be of the
              appropriate type for the particular attribute,  but
              should be cast to LM_A_VAL_TYPE.


NOTES

       Four additional attributes have been defined in lmsgi:

       LMSGI_NO_SUCH_FEATURE
              A  pointer  to  a function which is called when the
              requested feature  cannot  be  checked  out.   This
              function  is only called if license_chk_out() fails
              with an LM_NOFEATURE error.

       LMSGI_30_DAY_WARNING
              A pointer to a function which is  called  when  the
              requested feature will expire within 30 days.

       LMSGI_60_DAY_WARNING
              A  pointer  to  a function which is called when the
              requested feature will expire within 60 days.

       LMSGI_90_DAY_WARNING
              A pointer to a function which is  called  when  the
              requested feature will expire within 90 days.

              The   lmsgi   library   sets   default  values  for
              attributes in order to provide  standardized  error
              handling  and  error messages for SGI software.  To
              disable   a   pre-set   attribute,    either    use
              license_set_attr()  to register a new callback that
              provides your desired behavior, or register a  NULL
              callback to turn off the default behavior.


       LMSGI_NO_SUCH_FEATURE
              This  attribute is set to a function which displays
              information on how to get  a  license  for  an  SGI
              product.  This function also calls exit(), thus the
              application exits when the requested feature cannot
              be checked out.

       LMSGI_30_DAY_WARNING
              This  attribute is set to do nothing if the license
              is about to expire within 30 days.

       LMSGI_60_DAY_WARNING
              This attribute is set to do nothing if the  license
              is about to expire within 60 days.

       LMSGI_90_DAY_WARNING
              This  attribute is set to do nothing if the license
              is about to expire within 90 days.

       LM_A_USER_RECONNECT
              This attribute is set to a function which  displays
              a message noting that the connection to the license
              server was lost, and an attempt is  being  made  to
              reconnect to the server.

       LM_A_USER_RECONNECT_DONE
              This  attribute is set to a function which displays
              a message noting that the connection to the license
              server  was  lost,  and the attempt to reconnect to
              the server was successful.

       LM_A_USER_EXITCALL
              This attribute is set to a function which  displays
              a message noting that the connection to the license
              server was lost, and the attempt  to  reconnect  to
              the  server  has  failed.  This function also calls
              exit(), thus the application exits when the  recon­
              nect fails.


EXAMPLE

       /*
        * The following code sets the LM_A_RETRY_COUNT to 5.
        * If any errors are detected, then display them.
        */

       if ( license_set_attr(LM_A_RETRY_COUNT, (LM_A_VAL_TYPE) 5) ) {
               printf("Set attribute error: %s\n", license_errstr());
       }

       /*

        * within 90 days.
        */

       int expire_soon(daysLeft)
           int daysLeft;
       {
           (void) fprintf(stderr,
                          "Your software license will expire in %d days.\n",
                          daysLeft);

           return 0;
       }

       /*
        * The following code registers a callback for a license which
        * will expire soon.
        */

       if ( license_set_attr(LMSGI_30_DAY_WARNING, (LM_A_VAL_TYPE) expire_soon) ) {
               printf("Set attribute error: %s\n", license_errstr());
       }


DIAGNOSTICS

       license_set_attr()  returns  a  0  upon success or a value
       less than 0 if an error is detected.  The error string can
       viewed via license_errstr().

       license_expdate  - Returns the expiration date of the fea­
       ture checked out.


SYNOPSIS

       #include <lmsgi.h>

       time_t license_expdate(char *feature);


DESCRIPTION

       license_expdate() returns the expiration date of a feature
       (license).

       feature
              The name of the feature (license).


EXAMPLE

       /*
        * The following code returns the expiration date of the
        * feature, dummy.
        * If any errors are detected, then display them.
        */
       time_t feature_expdate;

       if ( ( feature_expdate = license_expdate("dummy") ) == -1 )
               printf ("Expiration date error: %s\n", license_errstr());


DIAGNOSTICS

       license_expdate() returns the expiration date of the given
       feature in seconds since 00:00:00 UTC,  January  1,  1970.
       If the given feature is a permanent feature (no expiration
       date) then  license_expdate()  returns  0.   If  an  error
       occurs, a value of (time_t)-1 is returned.

       Any error string can viewed via license_errstr().

       license_errstr  - Returns license server or system errors.


SYNOPSIS

       #include <lmsgi.h>

       char* license_errstr();


DESCRIPTION

       license_errstr() returns the FLEXlm error string  for  the
       most  recent  FLEXlm  error along with the major and minor
       number.  If a UNIX  error  is  involved,  the  UNIX  error
       description  will  also  be included in the message, along
       with the UNIX errno.


EXAMPLE

       /*
        * The following code prints out the error
        *
        *   Cannot find license file (-1, 73:2), No such file or directory
        *
        * when the license file cannot be accessed.
        *
        */

       printf ("%s\n", license_errstr());

       license_status - Returns the latest status of the  checked
       out feature.


SYNOPSIS

       #include <lmsgi.h>

       int license_status(char *feature);


DESCRIPTION

       license_status()  returns the status of the requested fea­
       ture (license).  A return value of 0 indicates a  success­
       ful return from the most recent call to the FLEXlm library
       for that feature.  A return value value less than 0  indi­
       cates  an  error  from  most  recent  call  to  the FLEXlm
       library.

       feature
              The name of the feature.


EXAMPLE

       /*
        * The following code checks the status of the most recent FLEXlm
        * library call.  If any errors occurred, then display them.
        */

       license_chk_out (&code, "dummy", "2.000");

       if ( license_status ("dummy") < 0 ) {
               printf ("error: %s\n", license_errstr());
       }

       get_job - Returns the FLEXlm job ID.


SYNOPSIS

       #include <lmsgi.h>

       LM_HANDLE *get_job(void);


DESCRIPTION

       Returns the FLEXlm job ID so that applications can use the
       standard FLEXlm functions along with the SGI interface.

       A  return  value of NULL indicates that there is currently
       no FLEXlm job ID.


EXAMPLE

       LM_HANDLE *job;
       job = get_job();

       The  FlexLM  licensing  code  uses  the  stdio   functions
       (fopen(),  fgets(), etc). In some circumstances, a process
       may have more open file descriptors than  will  fit  in  a
       FILE  structure (field _file; see /usr/include/stdio.h for
       details).  If this happens  before  the  licensing  calls,
       acquiring the license will fail with the message:

       Cannot find license file (-1,212:2) No such file or direc­
       tory

       The only solution is to reduce the number of file descrip­
       tors  in  use  when  licensing calls are made. In practice
       this is only a problem with the O32 (5.3 compatible)  ABI,
       which  uses  an  unsigned char to hold the file descriptor
       (fd<=255).


Man(1) output converted with man2html