Digital PDFs

AA-LA33A-TE

April 1990

24 pages

Original

0.8MB

Document:	The LMF User Primer
Order Number:	AA-LA33A-TE
Revision:	000
Pages:	24
Original Filename:

OCR Text

Digital Internal Use Only

The LMF User Primer
Order Number: preliminary

This document describes the DIGITAL Vendor-Specific Module (DVSM)
Interface to the VMSTM License Management Facility (LMF). This document
is divided into two parts: part one provides an overview of the LMF and part
numbering: part two describes the subroutine calls necessary to support LMF
in a layered product.
This document is intended for use with layered products only; no attempt is
made to explain the licensing scheme for the VMS system-integrated products
(SIPs).
Tabular information included herein is from the U.S. Price Book, 10-January1989.
For further information on the LMF, consult the License Management
Utility Manual, documentation part number AA-LA33A-TE. For internat..use
information on the Loan-of-Products program, consult. the Software Loan of
Products Guide, part number EE-C0290-76.
"The Unauthorized LMF Documentation"
contact Stephen (VOX::) HoffMan with comments
April 3',1990

Digital Internal Use 'Only

Part I LMF License Routines Primer

Digital Internal Use Only

2-5-2 Part Number Overview

1.1

Part Number Format
All new DIGITAL software part numbering is based on the same scheme.
The part number is broken down into a two character prefix, a five
character part number, and a two character suffix. The scheme is often
known as the 2-5-2 part number format. The 2-5-2 format looks like:

~
Chapter 1 describes the part number format in detail. The License
Management Facility, and the relationship of the LMF with part numbers,
is covered in Chapter 2.

1.1.1

The Prefix
The first two characters, known in the vernacular as the prefix, describe
the general classification of the part number. For example, the prefix
is what differentiates the software binary kit from the software license.
Table 1-1 shows the most common prefixes.

1.1.2

Table 1-1

SoftWare-Related License Prefixes

Prefix

Description

License

SPS Services

Media and Documentation kits

Packages Software Components

The Body
The middle five positions of the part number are comprised of three
characters for the Unique Product Identifier (UPI), one character for the
language variant (see Table 1-2) and the final character for the processor
type (see Table 1-3). A unique UPI is assigned to every software product
that DIGITAL sells.

Digital Internal Use Only

1-1

2·5-2 Part NU~'liber Overview

Table 1-2 License Language Types
Code

Description

American English

British English

Language Neutral

Table 1-3 License Processor COdeS

1.1.3

Code

Processor NamelSystem Marketing Model

MicroVAXTM 3500,3600

VAXstation 1M 3200, 3500, 8000, 3100, VAXserver™ 3500, 36mm, 3300,
3400

VAXTM 6240, 8800, 8820, 8820N

VAX 8700. 8550, 8810

VAX86W

VAX 8530, VAXserver 6220

VAX 83SS, VAXserver 6210

VAX 82SS, MicroVAX 3300, 3400

VAX 11n8S

VAX 11n50

VAX 11n30

MicroVAX II

MicroVAX 2000

VAXstation II

VAXstation 2000

VAX 8830

VAX 8840,8974,8842

PC Software

PDpTM Cross Product Generic

VAX 6210

VAX 6220

VAX 6230

VAX 8978

Processor Tier NeutraiNAX Cross Product Generic

The Suffix
The suffix, also known as the variant, contains information specific to the
part number prefix. Each prefix has a valid set of variants. Consult the
current price book for the possible variants.
1-2

Digital Internal Use Only

2-$02 Part Number Overview

For license (QL) part numbers, the general license type is in the first
position of the suffix (see Table 1-4), and license-specific information in
the second position (see the front of the software section in the current
price book for details).
Table 1-4 License Types
Type

License Type Description

Traditional License

ClusterWide License

Loan-of-Produds License

User/Activity Ucense

The LMF design allows great flexibility on licensing. For all 2-5-2 parts
with a QL prefix, the suffix calls out the type of license. The type of license
detennines what will appear on the PAK. Section 1.1.3.1, Section 1.1.3.2,
Section 1.1.3.3 and Section 1.1.3.4 describe the current, major flavours of
product licenses. Example 2-1 contains an example PAK.
1.1.3.1

Traditional Or Tiered Licenses

A traditional license provides the customer the right to execute a given
software product on a single processor.
The traditional license, license type A, is a tiered license; that is, the
cost of a license for the same product, when purchased for a faster VAX.
processor, is correspondingly higher. The LMF detennines the relative
processor performance by consulting the License Unit Requirement Table
(LURT). The LURT is provided and maintained by VMS; the LURT is
updated when new processors are released.
The first traditional license in a VAXcluster must be a standalone
traditional license. (A part number with an AA suffix) Subsequent
systems must use, if available, the AB cluster member license. If the
cluster member license, the AB license, is not available, the AA license
must be purchased. The AB license may remain in a VAXcluster only if
accompanied by an AA licensed system.
In LMF-speak, the tiered, per-processor, licenses are AVAILIBILITY
charged. See Section 2.1.3.3.
Example part numbers are:

DlgHal Internal Use Only

1-3

2-5-2 Part Number Ovei\{?f:~W

1.1.3.2

ClusterWlde Licenses

The ClusterWide License, license type J, provides for the execution of
layered products on all processors within a cluster provides that the
combined license rating of all processors within the cluster executing the
software at a given time shall not exceed the combined license rating of
the ClusterWide license(s) designated to the cluster for a given software
product.
Rephrased somewhat, a ClusterWide license provides a pool of license
units that are available for use by any system in the VAXcluster. When
a ClusterWide license is loaded (activated) on a specific processor, a
processor-specific number of units are deducted from the pool of available
units. Conversely, when a ClusterWide license is unloaded (deactivated)
the number of units deducted by the activation are returned to the
VAXcluster pool of available units. The specified software product is
licensed and is available for use only when the license units are loaded.
This license is purchased on a unit basis and is available for standalone
and well as VAXc1usters.
LMF supports a combination of the ClusterWide license with the
User/Activity license mentioned below. In LMF-speak, the ClusterWide
and tiered per-processor licenses are AVAILIBILITY charged. See
Section 2.1.3.3.
Example part numbers are:

1.1.3.3

User/Activity Licenses

The layered product user/activity license, license type P, is a per-user or
a per-activity license. This license restricts the number. of simultaneous
users, or activations, of the licensed product.
The User/Activity license is very similar to the ClusterWide license in
capabilities. The salient difference is the blanket licensing granted a
processor for the ClusterWide license. The User/Activity licenses provide a
finer granularity of licensing.
The LMF supports the User/Activity licensing scheme combined with
the ClusterWide licensing: a tiered per-processor charge, plus a charge
of activations. In LMF-speak the tiered per-processor charge is the
AVAILIBILITY charge. See Section 2.1.3.3. The per-user charge is the
ACTMTY charge. See Section 2.1.3.4.

An example part number is:

1.1.3.4

Loan-of·Products Licenses

The loan-of-products license, license type L, is a special-purpose license.
For information on the Loan-of-Products program, consult the Software
Loan of Products Guide, part number EE-C0290-76.

1-4

Digital Internal Use Only

LMFOverview

2.1

Product Authorization Key
Now for a brief overview of the VMS License Management Facility and the
Product Authorization Key (PAK).
Temporary Service PAKs (TSPs), used to fix customer problems and for
product demonstrations, are obtained from an LKG via the Customer
Support Centers. (See Table 2-1)
Products released before VMS V5.0 are required to issue a Service
Update PAK (SUP) with each release after VMS V5.0. All authorization
number fields for SUPs commence with the three characters "AWS". PAKs
intended for internal use are obtained from various sources depending on
employee location and planned usage for the PAl{: consult the notesfile
VOX::VOICE_PRODUCTS note 329.* for more information.
Table 2-1

2.1.1

Customer suppon Numbers

Number

Center

800·525·7100

Colorado Customer Support/Software

800·525·6570

Colorado Customer Support/Hardware

800·332·8000

Georgia Customer Support CenterlHW & SW

800·272·2001

Massacusetts Customer Support/HW & SW

The License Key Generator
The PAKs for all products are obtained from a License Key Generator
(LKG) system. Access to an LKG is typically subject to rather stringent
restrictions. Software Shipping Business (SSB, formerly SDC) has
access to an LKG for generation of PAKs for external sites and official
internal distributions. Software Quality Management (SQM) has an LKG,
currently located on MADRID::, used by product development to generate
PAKs for both internal and field test purposes.

2.1.2

The License Database
Licenses are stored in the license database. During bootstrap, the VMS
system loads all active, valid, unexpired licenses for the local node.
Licenses can also be loaded by an explicit DCL "LICENSE LOAD"
command. On node shutdown or crash, all licenses are released and
all availability and activity charges are cleared.

Digital Internal Use Only

2-1

LMF Overview

The license database can be shared across nodes in a VAXcluster™; again,
subject to the number of units available, the types of license(s) present,
and the terms and conditions of the license(s).
The ClusterWide™ licenses and all layered products typically use the
common license database file: SYS$SYSTEM:LMF$LICENSE.LDB.
This database is shared among all nodes in a VAXcluster. Some systemspecific licenses, such as VAX-VMS, reside in the system-specific database:
SYS$SYSTEM:LMF$SYSTEM.LDB.
By default, the DCL LICENSE command references the
LMF$LICENSE.LDB database. To alter the default database for a specific
DCL LICENSE command, specify the /DATABASE qualifier.
For further information consult the License Management Utility Manual,
documentation part number AA-LA33A-TE.

2.1.3

Breakdown of a License
The following sections describe the various component fields of a Product
Authorization Key.
An example PAK is located in Example 2-1. Table 2-3 contains a synopsis
of the various fields.

The major fields of a PAK are the product name, units, availability, and
activity fields. Various other fields may also be specified.
2.1.3.1

Product Name

The product name is the name of the product that is licensed. Each
product name is typically associated with a Unique Product Identifier
(UPI, see Section 1.1.2). The product name may represent a single
product, or it may be the name of a group of products sold together as
a package.
2.1.3.2

Number Of Units

The number of units field on the PAK controls the maximum number of
(completely arbitrary) units of license that can be used on the system. A
zero indicates there is no limitation. If specified, the key options field value
''MOD_UNITS'' allows the System Manager to modify the number of units
on a license, subject to the terms and conditions of the license.
2.1.3.3

Availability Table Code

The availability table code field determines the number of units to deduct
when the license is loaded (made available) on the VMS system. The code
can be a letter code, layered products typically use an F character, or it
can be a constant value, such as "CONSTANT=O". Table 2-2 contains the
complete list of valid availability codes.

2-2

Digital Internal Use Only

LMF Overview

The availibility codes used on many tiered products (see Section 1.1.3.1)
determine the specific charges used for the current processor. The
charge table for the current processor, broken down by the product
availibility codes, can be displayed with the DeL command SHOW
LICENSFJCHARGE_TABLE. The following charge table display is from a
VAX 8800:
$

SHOW LICENSE/CHARGE TABLE

VMS/LMF Charqe Info~tion for node VOX
This is a VAX 8800, hardware model type 18
Type: A, Units Required: 93
(VMS Capacity)
Type: B, * Not Permitted *
(VMS Server)
Type: C, * Not Permitted *
(VMS Concurrent User)
Type: 0, * Not Permitted *
(VMS Workstation)
Type: E, Units Required: 400
(System Inteqrated Products)
Type: F, Units Required: 1200
(Layered Products)

An availibility table code of F indicates VMS is to determine the unit
charge based on the standard processor tier unit charge from the License
Unit Requirement Table (LURT). The F availibility code is the traditional
tiered license, as implemented in the LMF environment. It is the most
common availability table code for DIGITAL layered products.

The "CONSTANT" option in the availability table code field forces a
constant number of units regardless of the processor. "CONSTANT=O"
indicates a license charged solely on the activity.
Table 2-2 Availability Codes

2.1.3.4

TYpe

License TYpe Description

VMS Capacitymmeshare

VMS Server

VMS Concurrent User

VMS Workstation

E
F
CONSTANT

VMS System Integrated Products
Layered ProdudllURT-based Charging
User/Activity License

Activity Table COde
The activity table code field, which is typically non-blank only on
"CONSTANT" availability licenses, controls the number of units deducted
for each instance of active use of the licensed layered product. The
LMF software dynamically determines the activity deduction for the F
availability code based on the License Unit Requirement Table (LURT)thus nothing is present in the activity table code field.

Digital Internal Use Only

2-3

LMF Overview

2.1.3.5

Miscellaneous Fields on the PAK
Table 2-3 describes the various fields found on a Product Authorization
Key. The contents of these fields vary, depending on the PAK.
Table 2-3 PAK Fields

2-4

Field

Description

Issuer

This field indicates the organization that issued the
PAK. For DIGITAL products. this field will typically be
set to DEC.

Authorization

This is a number used to track the PAK. A PAK with
the first three characers -AWS- is a Service Update
PAK (SUP).

Product Name

This is the LMF name of the licensed product. or
group of products.

Producer

This is the number of the product producer.

Units

This is the number of units available for the product.
For tiered licenses. zero indicates no limit.

Version

This is the numeric version number. in the form
mm.nn where mm is the major identifier and nn is the
minor identifer, of the highest product release that this
license can be used with. Cannot be combined with
product release date.

Release Date

This is the date of the final product release with which
the PAK can successfully be used on. The product
release date is advanced only when a new release of
the product is installed. This field has a use similar
to. but cannot be combined with, the product version
field. Not to be confused with termination date.

Termination Date

This is the last calendar date on which the PAK can
be used on. The PAl< is said to have expired when
the termination date has passed. Not to be confused
with release date.

Availability

The number of units deducted when the product is
made availabte. Explained in Section 1.1.3.3.

Activity

The number of units deducted when the product is
activated. Explained in Section 1.1.3.3.

Options

This field has various uses. most common are the
NO_SHARE and the MOD_UNITS settings. NO_
SHARE ties the PAK to a system. MOD_UNITS
allows modification of the units field.

Product Token

This field is typically not used.

Hardware-ID

This field is typically not used.

Checksum

This field contains a checksum of all the other fields
on the PAK. The first character of the checksum
field is a numeric, the rest of the checksum contains
alphabetic characters only.

Digital Internal Use Only

LMF Overview

2.2

Part Numbers and the LMF
Now for the tie-in with the layered product part numbers: an LMF
availability code of F has a part number with a prefix of ItQL_ It, the product
UPI, language and processor, and a suffix. (See Table 2-4) User/Activity
licenses have a suffix from Table 2-0).
The License Key Generator (LKG) system used by SBB (formerly SDC)
parses the part number for content and validity, and in the case of a
user/activity license, multiples the number of users (indicated by the final
character in the 1t_p*1t suffix) times the value of the activity constant to
determine the number of units to generate on the customer PAK.
Table 2-4 Tiered License Suffixes
Suffix

Description

Traditional License

Traditional VAXcluster License

Other variants-see the price book

Loan-of-Products License

First ClusterWide License

Subsequent ClusterWide Licenses

Table 2-5 Non-Tiered License Suffixes
Suffix

Description

Loan-of-Products License

User/Activity License

An example Product Authorization Key is located in Example 2-1.

Digital Internal Use Only

2-5

LMF Overview

Example 2-1

PAK Example

I I I I I I I I
Idlilgliltlalll
I J I I I I I I

LICENSE SOFTWARE PRODUCT
PRODUCT AUTHORIZATION KEY

DOCUMENT ISSUE DATE
14-APR-1989

Digital Equipment Corporation
Maynard, MA.
LICENSE ADMINISTRATION LOCATION:
Digital Equipment Corporation
Software Quality Management/
Systems Quality Group
110 Spit Brook Road
Nashua, N.H. 03062

ORDERED BY: Enterprise Eng.
Dept. NCC-1701D
San Francisco, CA.

********************************************************************
PAK ID:
Issuer: DEC
Authorization Number: SQH006887

PRODUCT ID:
Product Name: VOX
Producer: DEC
NUMBER OF UNITS:
Number of units: 0
KEY LEVEL:
Version: 1.1
product Release Date:
KEY TERMINATION DATE:
Key Termination Date: 31-JUL-l989
RATING:
Availability Table Code: F
Activity Table Code:
MISCELlANEOUS:
Key Options: MOD_UNITS
Product Token:
Hardware-Id:
Checksum: I-BOGU-SCHE-CKSU-MMIS
*****.**************************************************************

2-6

Digital Internal Use Only

Part II LMF License Routines

Digital Internal Use Only

LMF LI~:$l\se Routines
SYS$LOOKUP_LICENSE

SYS$LOOKUP_LICENSE
SYS$LOOKUP_LICENSE is intended to be the primary interface for the
VAXNMS Ucense Management Facility for DIGITAL layered products. The
routine will grant the caller pennission to continue exeQJtion if a valid Bcense
exists for the specified product. SYS$LOOKUP_LICENSE is part of the
DIGITAL Vendor-Specific Module (DVSM).

FORMAT

SYS$LOOKUP_LICENSE

RETURNS

VMS Usage: cond_value
type:
longword (unsigned)
access:
wrHe only
mechanism: by value

ARGUMENTS

PRDNAM, ITMLST,
PRODUCER lFLAGS ,
CONTXT, LICPROD

PRDNAM
VMS Usage: char_string
type:
character string
access:
read only
mechanism: by descriptor

The product name corresponding to the name on the product authorization
key license.

ITMLST
VMS Usage: Hem_lIst_3
type:
longworcl (unsigned)
access:
read only
mechanism: by reference

This is the address of a contiguous array of standard VMS three-Iongword
item list structures. The item list must contain at least the items LMF$_
PROD_DATE and LMF$_PROD_VERSION. The item list is terminated
with a zero-filled entry.
3

LMF$_PROD_DATE, the quadword binary date when the software is
to be released. This date must always be prior to the SBB shipment

date. PAKs issued internally are currently coded with a release date
ONE YEAR after the date the internal-use PAK is issued. A product
will work with any PAK with a release date in the future relative to
the release date coded into the program. (this argument establishes
the release date that is coded into the product.)

Digital Internal Use Only

\LMF License Routines
SYS$LOOKUP LICENSE

LMF$_PROD_VERSION, the product version is encoded into a
longword field. The upper word is the product major version, the
lower longword is the minor version. If the version encoded into the
product LMF call is less than, or equal to, the product version on the
PAK., this part of the check with succeed. (This argument establishes
the version coded into the product.)

PRODUCER
VMS Usage: char_string
type:
character string
access:
read only
mechanism: by descriptor
The product producer. This argument must be defaulted to zero or must
be specified as the address of a descriptor referencing the string "DEC".

FLAGS
VMS Usage: longword_unslgned
type:
longword (unsigned)
access:
read only
mechanism: by reference
A flags longwor<\ containing various control bits.
/~,

LMF$V_RETURN_FAILURES, when set, indicates the procedure witir ""'; \
return both success and failure status to the calling routine. If this
flag is clear or false, the procedure will signal all failure conditions.

LMF$V_BROADCAST_FAILURES, when set, OR if the logical name
LMF$DISPLAY_OPCOM_MESSAGE is defined, an OPCOM message
will be broadcast to all LICENSE operators on any license failures.

LMF$V_OUTPUT_FAILURES, if set and LMF$V_SIGNAL_
FAILURES is false, license failures will result in one or more messages
being output to the user via SYS$PUTMSG.

CONTXT
VMS Usage: context
type:
octaword (unsigned)
access:
wrHe only
mechanism: by reference
This octaword contains the license authorization context required for
license release by SYS$RELEASE_LICENSE. This argument is required
only for user/activity licenses-licenses that should be released prior to
image run-down.

LICPROD
VMS Usage: char_string
type:
character string
access:
write only
mechanism: by descriptor
Will be loaded with the product name of the actual product or group
licensed. This can be different than the PRDNAM field if the product is
part of a group license. The field is 24 bytes and is fixed length.
Digital Internal Use Only

LMF License Ro"ih~es
,SYS$LOOKUP_LICENSE

DESCRIPTION

SYS$LOOKUP_LICENSE implements a DIGITAL-specific interface to
the SYS$GRANT_LICENSE system service. The routine is designed
specifically for use by DIGITAL layered products and includes the notion
of a product group.
The procedure is not intended for use by customers or by non-DIGITAL
software as it incorporates a number of DIGITAL-specific business rules.
SYS$LOOKUP_LICENSE calls the system service SYS$GRANT_
LICENSE. All DIGITAL layered products should call SYS$LOOKUP_
LICENSE, rather than calling SYS$GRANT_LICENSE, for consistency
across all licensing implementations.
The LICENSE$_xxx return status codes are defined in, among other
places, SYS$SHARE:STARLET.MLB, in the module $LICENSEDEF.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Routine successfully completed.

L1CENSE$_BADPARAM

Product name length too large or return product length
buffer is too small.

L1CENSE$_ILLPROOUCER

Producer argument isn't -DEC-.

L1CENSE$_WRONUMARG

Too few or too many arguments were specified.

L1CENSE$_NOAUTH

All attempts to grant access to the caller failed.

L1CENSE$_SYSMGR

Information signaled with LlCENSE$_NOAUTH.

LICE NSE$_NOT_STARTED

LMF has not yet been started.

STR$~xx

Invalid string parameter specified.

Dlgnal Internal Use Only

LMF License Routines
SYS$RELEASE_LICENSE

SYS$RELEASE_LICENSE
SYS$RELEASE_LlCENSE revokes a process' authorization to exeQJte a
licensed software product. The authorization must have been previously
granted by a call to SYSSGRANT_LICENSE or to the DIGITAL-specific routine
SYSSLOOKUP_LICENSE.

FORMAT

SYS$RELEASE_LICENSE

RETURNS

VMS Usage: cond_value
type:
longword (unsigned)
access:
wrHe only
mechanism: by value

ARGUMENTS

CONTXT

CONTXT
VMS Usage: context
type:
octaword (unsigned)
access:
wrHe only
mechanism: by reference
License authorization context from a call to SYS$LOOKUP_LICENSE or
SYS$GRANT_LICENSE.

DESCRIPTION

SYS$RELEASE_LICENSE revokes a process' authorization to execute
a licensed product. This subroutine is generally useful for user/activity
licenses only.
SYS$RELEASE_LICENSE is available to release licenses prior to image
run-down. This routine allows the implemwentation of user or activity
based licenses.
The LICENSE$_xxx return status codes are defined in, among other,
places, SYS$SHARE:STARLET.MLB, in module $LICENSEDEF.

CONDITION
VALUES
RETURNED

SS$_NORMAL

Routine successfully completed.

SS$_xxx

System service error.

,Digital Internal Use Only

LMF License Routines
SYS$GETLUI

SYS$GETLUI
SYS$GETLUI returns information about the in-memory license database.
SYS$GETLUI is not yet implemented.

FORMAT
RETURNS

ARGUMENTS

SYS$GETLUI

PRDNAM, PRODUCER, ITMLST

VMS Usage: cond_value
longword (unsigned)
access:
write only
mechanism: by value

type:

PRDNAM
VMS Usage: char_string
type:
character string
access:
read only
mechanism: by descriptor
The product name corresponding to the name on the product authorization
key license.

PRODUCER
VMS Usage: char_string
type:
character string
access:
read only
mechanism: by descriptor
Address of a descriptor containing the product producer. The argument
must be defaulted to zero or specified as a string descriptor for the ASCII
string "DEC".

ITMLST
VMS Usage: ltem_lIst_3
type:
Iongword (unsigned)
access:
read only
mechanism: by reference
Address of a contiguous array of standard VMS three-longword item list
entries. The list is terminated with an itemlist entry containing zeroes.

DESCRIPTION

The SYS$GETUAI call is not currently implemented.
The LICENSE$..xxx return status codes are defined in, among other
places, SYS$SHARE:STARLET.MLB, in module $LICENSEDEF.

Dlgllallnternal Use Only

LMF License Routines
SYS$GETLUI

CONDITION
VALUES
RETURNED

SS$_NORMAl

Routine successfully completed.

SS$_EXENQlM

Process has exceeded its ENQUEUE authorization
quota.

SS$JNSFVM

Sufficient system dynamic memory does not exist to
allocate the lock or resource block.

SS$_ACCVIO

Product or producer strings cannot be read, or the
itemlist buffers cannot be read or written by the calling
access mode.

SS$_BADPARAM

Invalid iten code specified.

lICENSE$_NOllCENSE

No license exists for this product in the in-memory
database.

lICENSE$_NOT_STARTED

LMF has not yet been started.

STR$_xxx

Invalid string parameter specified.

Digital Internal Use Only

Program Example

A VAX C example program that makes calls to the routines of the
DIGITAL vendor-specific module (DVSM) is shown in Example A-l.
Example A-1

DVSM LMF Program Example

.module vox$$checks -Il.l-OOl/*

1* vox$$lmf check()
1* vox$$lmf=cashin()
1*
1*
/* vox$$lmf check.c
1* this subroutine is used to check for a hardwired product
1* license. If the license is not installed the subroutine
1* signals the error.
/*

1*
1*
1*
1*
/*
/*

1*
1*
1*
1*
1*
1*
1*
1*
/*

voxSSlmf_check ( [product, flags, contxt ) [, itmlst) )
product addr (or a zero) of a descr of the product to
check for (which, for our purposes, defaults to
a descriptor to the product ·VOX-)
flags

addr of ~F flags longword to be passed into LMF.

contxt addr (or zero) of a LONGWORD used to hold the
address of a dynamically allocated block that
holds the ~F context OCTAWORD for releasing
license. (needed for userlactivity lice only.)
itmlst is the address of an itemlist 3 structure to be
passed in. Not currently used. This hook allows
(even weirder) variant calls and argument lists.

modified:
lO-Mar-l989 Hoffman
1* account for VOX FTl Vl.l dates; allow a couple of
1* [optional) parameters so that we do not necessary
/* go down in flames if the license is not registered.
1* (we can now return a polite NOLICENSE status ••• )
/* 19-Apr-l989 Hoffman
/* Shuffled the argument list around. Added a context
/* argument so that user/activity licenses can be
/* released. And added the vox$$lmf cashin() routine
/* to actually perform the releasing:
*1
/*

1*
/*

The following four definitions are the defaults. Change
these and you can check any product (by default):

.define PRODUCT -VOX·
.define PRODUCER -DEC·
.define PROD VERSION Ox01000l
'define PROO=OATE -1-MAR-1989-

Example A-1 Cont'd on next page

Digital Internal Use Only

Program Example

Example A-1 (Cont.)

DVSM LMF Program Example

1*
1* Definitions required to get off the ground: (note that
1* the LMF stuff does not yet have a C header file ••• VAX
1* C V3.0 cures this by adding the LMFDEF.H file.)
*1
.include Nsys$share:stsdef.h N
'include Nsys$share:ssdef.h N
'include NsysSshare:syidef.h N
'include NsysSshare:descrip.h N
.include NsysSshare:varargs.h N
.define LMFSM RETURN FAILURES
.define LMFSM-BROADCAST FAILURES
.define LMFS PROD VERSION
3
.define LMFS=PROD=OATE
4

OxOl
Ox02

.1fdef TEST_MAIN
1*
1* Test main program -- for debugging purposes only.
1* Use the command NCC/DEFINE-TEST MAIN file.c N to
1* enable this stub main program. ./

main ()
MAIN PROGRAM

unsigned long int retstat;
unsigned long int ctx - 0;
SDESCRIPTOR( Imfcrecog, ·VOX-CRECOG N );
SDESCRIPTOR( lmfvox, ·VOX N );

1*
/*

See if default LMF NVOX· cheCk works.

LMF -- fully defaulted / no arguments\n N);
retstat s voxSSlmf check();
if (!SVMS_STATUS_SUCCESS( retstat » LIBSSIGNAL( retstat );

p~intf(Mchecking

/*
/*

See if non-default LMF ·VOX" check works.

printf(Nchecking LMF -- 3 args I traditional license\n N);
retstat • voxSSlmf check( &lmfvox,
&LMFSM RETURN FAILURES, 0 );
if (!SVMS_STATUS_SUCCESS( retstat » LIBSSIGNAL( retstat );

1*
/. Check a user/activity license -- retaining context for
/* the eventual release.
*1
printf(Nchecking LMF -- 3 args I user-activity license\n N);
retstat - voxSSlmf_check( &lmfcrecog,
&LMFSM RETURN FAILURES, &ctx );
if (!SVMS_STATUS_SUCCESS( retstat » LIBSSIGNAL( retstat );
1*
/* And
*/

return what we have used in the above check

printf(Nchecking LMF -- releasing user-activity license\n");
retstat • voxSSlmf cashin( &ctx )1
if (ISVMS_STATUS_SUCCESS( retstat » LIBSSIGNAL( retstat );
return( SSS_NORMAL )i
}

.end1f

Example A-1 Cont'd on next page

Digital Internal Use Only

Program Example

Example A-1 (Cont.) DVSM LMF Program Example
voxSSlmf_check( v~_~list
va dcl
- (
va list apt
int retstat;
int SYSSLOOKOP LICENSE();
SOESCRIPTOR( product, PRODUCT );
SDESCRIPTOR( producer, PRODUCER );
SOESCRIPTOR( prod date, PROD DATE );
char retprodnambuf[25);
struct dscSdescriptor retprodnam •
24, DSCSK DTYPE T, OSCSK CLASS S, retprodnambuf I;
int prod-version. PROD-VERSION;
int argcnt;
unsigned long int *usrflags;
unsigned long int *usreontxt;
unsigned long int *contxt;
struct dscSdeseriptor *usrproduct;
char bintim(8];
struct itmlst_3
short buflen;
short itmcod;
int bufadr;
int bufrla;
} itmlst(3J, *usritmlst;
va start ( ap ):
va-count ( argent I;
switch ( argcnt )
case 0:
usrproduct - 0;
usrflags = 0;
usrcontxt - 0;
usritmlst - 0;
break;
case 3:
usrproduct • va arg( ap, struct dscSdescriptor * )i
usrflags - v~ arg( ap, unsigned long int *);
usrcontxt - va_arg( ap, unsigned long int • );
usritmlst .. 0;
break;
case 4:
usrproduet - va arg( ap, struct dscSdescriptor * );
usrflags - va arq( ap, unsigned long int *);
usrcontxt - va arg( ap, unsigned long int • );
usritmlst .. va=arg( ap, struct itmlst_3 *):
break;
default:
retstat - LIBSSIGNAL( SS$ BADPARAH )i
return ( SSS_BADPARAM); break:

1*
1* Fill in the item list required by the call. Includes
1* the required final, zero-filled, block. This call will
1* pass the version and release date checks if the currently
1* loaded PAK is of a more recent product version or of a
1* more recent product release date. (And the termination
1* date on the PAK has not passed, and various other checks
1 * succeed.)
*1
itmlst{O].buflen • 8;
itmlst{O].itmcod - LMFS PROD DATE;
itmlst(O).bufadr • bintlm;
itmlst(O).bufrla .. 0;

Example A-1 Cont'd on next page
Digital Internal Use Only

P~i:,~Y~m Example

Example A-1 (Cont.)
itmlst(l).buflen itmlst[l).itmcod itmlst[l).bufadr itmlst[l).bufrla -

DVSM LMF Program Example

4;
LMFS PROD VERSION;
&prod version;
0;
-

itmlst(2].buflen - itmlst(2] .itmcod - 0;
itmlst[2].bufadr - itmlst[2] .bufrla - 0;
/*
/*

convert the time from human-readable ASCII to the
/* internal binary quadword format.
*/

retstat - SYSSBINTIM( &prod date, bintim );
if ( retstat !- SSS NORMAL)
LIBSSIGNAL( retstat );/*

/* Deal with the usrcontxt argument.

If it's present,
/* it must contain a zero. (Signal an error if it
/* doesn't -- programming error) If it's not present,
/* then assume this is not a user/activity license.
*/

if ( (int)usrcontxt
{

i f ( (* (int*)

usrcontxt ) )
LIBSSIGNAL( SSS BADPARAM );
else contxt = *usrcontxt = malloc( 32 );
}

else
contxt ,. 0:
}

1*
1* The LMF signals on errors in the zero-argument
1* version. In the two argument version it does
1* what you ask it •••
*1
if ( ! «int)usrproduct » usrproduct = 'product;
retstat = SYSSLOOKUP LICENSE( usrproduct,
&itmlst, &producer, usrflags, contxt, 0 );
return ( retstat );
}

/*
/*

/*
1*
/*

1*
/*
1*
/*
/*
/*
/*
/*
*/

voxSSlmf cashin( usrcontxt )
Cash in any license units we've used -- releasing
them back to the available pool. (Only needed if
releasing them on process run-down doesn't cut It.
This is typically only required for user/activity
licensing.)
usrcontxt is the address of a longword. This
lonqword references the octaword dynamically
allocated.
(This means the caller (hypothetically)
has one less thing to aim at the proverbial foot
-- there is no second longword to trash a variable.)

voxSSlmf cashin( usrcontxt )
unSigned-long int *usrcontxt;
{

int retstat;
int SYSSRELEASE LICENSE();
unsigned long int contxt - *usrcontxt:
*usrcontxt - 0:
retstat = SYSSRELEASE_LICENSE( contxt );
free( contxt );

Example A-1 Cont'd on next page
Digital Internal Use Only

Program Example

Example A-1 (Cont.)

DVSM LMF Program Example

return ( retstat )i
}

Dig Hal Internal Use Only