View source for Using SYSLEVEL Files in Your Applications

''Written by [[Martin Lafaix]]''

== Introduction ==
=== What's that? ===
Determining a computer software configuration has always been a tricky process. It would be great to have a standard way for registering applications, so that we could easily query the system configuration. But wait a minute! OS/2 provides the SYSLEVEL command, which does just that (it even tells us the various component versions)! If only we could use it for our own purposes...

=== Why? ===
This registering ability proves its usefulness when writing (relatively) large projects or components. For example, if you write a public toolkit or tools other programs may use, it would be a good idea to register them.
(OS/2 already uses it this way: on my home system, the syslevel command tells me that MMPM/2 and the Developer's toolkit are present - the same thing occurs if you have Communication Manager, etc.) When distributing such a tool, tell your users your component name and ID; it would then be easy for them to write an installation procedure which checks your component presence.

Another interest is that it helps component writers in creating CSD or component updates. As each SYSLEVEL file maintains a current CSD level as well as a previous CSD level field, it's easy to check what to update, and what to leave alone.

It's also useful while maintaining a computer network. It would provide the maintainer an up-to-date information database.

=== Contents ===
This article contains two parts. The first one describes the SYSLEVEL file format. The second part describes the two proposed APIs (one for C, and one for Rexx).

== A Voyage to Syslevel ==
When you start SYSLEVEL.EXE, it scans all your drives for SYSLEVEL files. These files are named SYSLEVEL.xxx (where xxx is any three-letters extension), and have a specific header. When one such file is found, it is displayed, as shown in figure 1. So, to be able to use SYSLEVEL for our own purpose, we'll have to decrypt SYSLEVEL's file headers, and find out how
(and where) to store our own data.
 C:\MMOS2\INSTALL\SYSLEVEL.MPM
                              Multimedia Presentation Manager 2
 Extensions systŠme 1.10     ID de composant 562137400
 Type MMPM\2
 Niveau de modifications en cours : UN00000
 Niveau de modifications ant‚rieur : UN00000
''Figure 1.  Syslevel output sample (French version, sorry :-) )''

=== On the File Header ===
A SYSLEVEL file header looks like the following:

 typedef struct _SYSLEVELHEADER {
    unsigned char h_magic[2];
    unsigned char h_name[9];
    unsigned char h_reserved1[4];
    unsigned char h_updated;
    unsigned char h_reserved2[17];
    ULONG         h_data;
 } SYSLEVELHEADER;
''Figure 2.  The SYSLEVELHEADER structure.''

;h_magic
:is the magic cookie. Its value is 0xFFFF.
;h_name
:is the string "SYSLEVEL", in uppercase and null-terminated.
;h_reserved1
:meaning unknown. Set to zero.
;h_updated
:was 1 for OS2, GRE and MPM, and 0 for TLK. My guess: set it to zero.
;h_reserved2
:meaning unknown. Set to zero.
;h_data
:points to the beginning of the file's data structure (offset from the beginning of the file), which is described below.

While I realize there's still many holes in there, it appears to fulfill our needs; namely, we are now able to create files recognized by SYSLEVEL.EXE. Isn't that great?

But it's time to learn more...

=== The SYSLEVEL Data Structure ===
In the previous section, we have seen that the file's data structure starts at offset h_data.  This structure (aka. the SYSLEVEL data structure) looks like the following:

 typedef struct _SYSLEVELDATA {
    unsigned char d_reserved1[2];
    unsigned char d_kind;
    unsigned char d_version[2];
    unsigned char d_reserved2[2];
    unsigned char d_clevel[7];
    unsigned char d_reserved3;
    unsigned char d_plevel[7];
    unsigned char d_reserved4;
    unsigned char d_title[80];
    unsigned char d_cid[9];
    unsigned char d_revision;
    unsigned char d_type[1];
 } SYSLEVELDATA;
''Figure 3.  The SYSLEVELDATA structure.''

;d_reserved1
:set to zero...
;d_kind
:specifies the component "kind". It can be any of the following:
* SLK_BASE (0)   "Base version"
* SLK_EXTENSION (2)   "System extension"
* SLK_STANDARD (15)   Neither "Base version" nor "System extension"... :-)

Any other value is equivalent to SLK_STANDARD (except 1, which is equivalent to SLK_EXTENSION).

;d_version
:specifies the component version. Its format is a bit strange:
the four high-order bits of '''d_version[0]''' contains the major version number, the four low-order bits contains the first minor version digit, and <b>d_version[1]</b> contains the second minor version digit.

For example, if '''d_version[0]''' is 0x21 and d_version[1] is 0x02, you will get "2.12".

[You can have a revision level, as in "2.12.a".  See <b>d_revision</b> below.]

;d_reserved2
:oh no, not again.  Set to zero.
;d_clevel
:specifies the current CSD level. It's a seven-byte string, usually in the form "AAC####", where AA is a two-byte string, C a country-dependent code, and #### a number. For example, on my home computer, I get "XRF2010" for the base operating system (It's the French version), and "XR02100" for the developer's toolkit (US version, this time).

It's just a suggested usage and is not enforced in any way. As long as you use seven printable characters, it should work.

;d_reserved3
:guess what? You lose! Set to 0x5F this time.
;d_plevel
:specifies the previous CSD level. If there was no previous level; set it equal to the current level, d_clevel.
;d_reserved4
:is just like d_reserved3; set to 0x5F
;d_title
:specifies the component name. It's a null-terminated string.
;d_cid
:specifies the component ID. It's not null-terminated.
;d_revision
:specifies the component revision. It does not appear in the version field if sets to zero. If it's not null, it will be concatenated with major and minor version number, as in "1.2.3" (where 1 is the major version, 2 the minor and 3 the revision). If you prefer a letter in place
of a digit, just increment the revision number by 0x10 for an upper-case letter, or by 0x30 for a lower-case. That is, if d_revision is 0x11, you will get an "A", and so on.
;d_type
:specifies the component type. It's an optional, null-terminated string. This field allows you to store additional informations for your component. For example, this field is used to differentiate the blue and salmon distribution of OS/2 (a type of '0-2' indicates the 'salmon' one).

Well, enough said on this exploration. It's time to go back to much safer places...

== Home, Sweet Home ==
This walk was fun, but all good things must come to an end. So we are back. And it's time to write some functions to comfort our precious new knowledge, isn't it?

Two APIs are available, a C one and a REXX one.

=== The SYSLEVEL C API ===
This section describes the API which provides access to the syslevel files. The corresponding code is in CLEVEL.ZIP. It's just an include file, level.h and a small C file, level.c which can be included, say, in your favorite library. It has been tested with GCC/2, but it should work with any other C compiler...

 APIRET LvlOpenLevelFile(PSZ pszName, PHFILE phFile, ULONG ulOpenMode, PSZ pszCID)
 
 APIRET LvlCloseLevelFile(HFILE hFile)
 
 APIRET LvlQueryLevelFile (PSZ pszName, PSZ pszCID, PVOID pBuffer, ULONG ulBufSize)
 
 APIRET LvlQueryLevelData(HFILE hFile, ULONG ulWhat, PVOID pBuffer, ULONG ulBufSize, PULONG pulSize)
 
 APIRET LvlWriteLevelData(HFILE hFile, ULONG ulWhat, PVOID pBuffer, ULONG ulBufSize, PULONG pulSize)

==== Design considerations ====
This API has been modeled upon the profile (Prf) functions.

==== Examples ====
The following two figures show how to check for the existence of a component, and if a component needs updating, respectively.
<code>
 :
 #include <level.h>
 :
 int main()
 {
   HFILE hFile;
   :
   if(hFile = LvlOpenLevelFile("DBM",
                               OLF_SCANDISKS | OLF_CHECKID,
                               "123456789"))
     /* present */
     :
   else
     /* not present */
     :
   :
   LvlCloseLevelFile(hFile);
   :
 }
</code>
Figure 4.  Syslevel API usage sample - Checking for the existence of a component
<code>
 :
 #include <level.h>
 
 :
 BOOL _needUpdate(HFILE hFile)
 {
   CHAR achCSD[7];
   ULONG ulCount;
 
   if(LvlQueryLevelData(hFile, QLD_CURRENTCSD, achCSD, 7, &ulCount))
     /* shall we update it? */
     return strncmp(achCSD, "DBF0099",7) <= 0; /* for example */
   else
     /* an error occurred */
     :
 }
 :
</code>
Figure 5.  Syslevel API usage sample - Shall we update component?

=== The SYSLEVEL REXX API ===
Well, it's not really an API, it's in fact a single function. The corresponding code is in RLEVEL.ZIP. It's just a REXX file, named REXXLVL.CMD. Put it somewhere along your PATH. The zip file also contains MAKESYSL.CMD, which can be used to create SYSLEVEL files.

This function has been modeled upon the STREAM function.
 RexxLvl()

==== Example ====
The following example is a REXX script. It allows you to easily create syslevel files.
<code>
 /* makesysl.cmd                                          940327 */
 
 say 'Component name:';                  parse pull name
 say 'Component ID:';                    parse pull ID
 say 'Component type (optional):';       parse pull type
 say 'Component version (as x.y[.z]):';  parse pull version
 say 'Current CSD Level:';               parse pull CSD
 say 'Component extension:';             parse pull ext
 
 file = RexxLvl("n", ext, ID)
 call RexxLvl "s", file, "n", name
 call RexxLvl "s", file, "c", csd
 call RexxLvl "s", file, "v", version
 call RexxLvl "s", file, "t", type
 rc = RexxLvl("c", file)
 
 if rc = 0 then say 'SYSLEVEL.'ext' created.'
</code>
Figure 6.  Creating a syslevel file in REXX.

== Summary ==
Now you have enough information to use the SYSLEVEL files well. However, the advertised advantages would become a reality only if we use SYSLEVEL files extensively. So, if you like these perspectives, use them, ask them, require them, again and again, until you get satisfaction.  :-)

As a sidenote, the information exposed in the first part of this article is the result of my own exploration. If you find any inaccuracy or if you have more information, please, let me know.

=== kind ===
;SLK_BASE:denotes a "base" component.
;SLK_EXTENSION:denotes a system extension.
;SLK_STANDARD:denotes a "standard" component. It's the suggested component kind value.

=== ulOpenMode - input ===
;ULONG:field that describes the mode of the open function.
;OLF_OPEN:open the specified file. The default behavior is to scan the current disk, starting from the current directory. It returns the first SYSLEVEL file whose extension matches pszName  You can override this by combining OLF_OPEN with OLF_SCANDISK or OLF_CHECKID.
;OLF_SCANDISKS:scans all disks (starting from C:). Use this flag to modify the default OLF_OPEN behavior.
;OLF_CHECKID:finds file(s) whose ID matches the specified one. Use this flag to override the default OLF_OPEN behavior.
;OLF_CREATE:creates the specified file in the current directory. A valid pszName and ID should be provided.

=== ulWhat - input ===
The following flags can be used when querying (or writing) a SYSLEVEL file.

;QLD_MAJORVERSION:Query (or update) the major version field. It's a one-character field. It should be in the range '0'-'9'. The value is placed in (or taken from) the first character of pBuffer. (Buffer size should be at least 1.)
;QLD_MINORVERSION:Query (or update) the minor version field. It's a two-character field. It should be in range '00'-'99'. The value is placed in (or taken from) the first two chars of pBuffer. (Buffer size should be at least 2.)
;QLD_REVISION:Query (or update) the revision field. It's should fit in a character. If it's '0', there's no revision available. It can be a letter as well as a digit. The value is placed in (or taken from) the first character of pBuffer. (Buffer size should be at least 1.)
;QLD_KIND:Query (or update) the kind field. The value is placed in (or taken from) the first character of *pBuffer. (Buffer size should be at least 1.)
;QLD_CURRENTCSD:Query (or update) the current CSD level (when you update this field, its old value is copied to the old CSD level field). It's a seven-character field, and it does not have to be full-terminated. The value is placed in (or taken from) the first seven characters of pBuffer. (Buffer size should be at least 7.)
;QLD_PREVIOUSCSD:Query the previous CSD level. You can't update this field. The value is placed in the first seven chars of pBuffer. (Buffer size should be at least 7.)
:Note: CSD levels are not null-terminated. Be careful when using such a returned value.
;QLD_TITLE:Query (or update) the component title field. It's an eighty-character string (required ending null included). The value is placed in (or taken from) the first eighty characters of pBuffer. On input, the buffer size should be at least 80. On output, the buffer size can exceed 80, but the written string is truncated (and null-terminated) to eighty characters.
;QLD_ID:Query (or update) the component ID field. It's a nine-character field. It does not have to be null-terminated. The value is placed in (or taken from) the first nine characters of pBuffer. (Buffer size should be at least 9.)
:Note: IDs are not null-terminated. Be careful when using such a returned value.
;QLD_TYPE:Query (or update) the component type field.

== LvlOpenLevelFile ==
 APIRET LvlOpenLevelFile(PSZ pszName, PHFILE phFile, ULONG ulOpenMode, PSZ pszCID)
Use this to find, open or create a SYSLEVEL file.

It returns the following values:
 0   NO_ERROR
 2   ERROR_FILE_NOT_FOUND
 3   ERROR_PATH_NOT_FOUND
 4   ERROR_TOO_MANY_OPEN_FILES
 5   ERROR_ACCESS_DENIED
 12  ERROR_INVALID_ACCESS
 26  ERROR_NOT_DOS_DISK
 32  ERROR_SHARING_VIOLATION
 36  ERROR_SHARING_BUFFER_EXCEEDED
 82  ERROR_CANNOT_MAKE
 87  ERROR_INVALID_PARAMETER
 99  ERROR_DEVICE_IN_USE
 108 ERROR_DRIVE_LOCKED
 110 ERROR_OPEN_FAILED
 112 ERROR_DISK_FULL
 206 ERROR_FILENAME_EXCEED_RANGE
 231 ERROR_PIPE_BUSY

=== pszName - input ===
The syslevel file extension. It's a three-letter, null-terminated string. That is, LvlOpenLevelFile deals with syslevel files named syslevel.xxx, where xxx is pszName's value.

== LvlCloseLevelFile ==
 APIRET LvlCloseLevelFile(HFILE hFile)

Use this to close a SYSLEVEL file. It's just a DosClose alias, for API consistence.

It returns the following values:
 0   NO_ERROR
 2   ERROR_FILE_NOT_FOUND
 5   ERROR_ACCESS_DENIED
 6   ERROR_INVALID_HANDLE
 
== LvlQueryLevelData ==
 APIRET LvlQueryLevelData(HFILE hFile, ULONG ulWhat, PVOID pBuffer, ULONG ulBufSize, PULONG pulSize)

Use this to query an already opened SYSLEVEL file.

It returns the following values:
 0     NO_ERROR
 6     ERROR_INVALID_HANDLE
 87    ERROR_INVALID_PARAMETER
 122   ERROR_INSUFFICIENT_BUFFER
 
When it returns ERROR_INSUFFICIENT_BUFFER, *pulSize contains the minimum requested size.

=== pBuffer - input/output ===
Address of the buffer that contains the data to write/read.

=== pulSize - output ===
Address of the variable to receive the number of bytes actually read or written.

== LvlWriteLevelData ==
 APIRET LvlWriteLevelData(HFILE hFile, ULONG ulWhat, PVOID pBuffer, ULONG ulBufSize, PULONG pulSize)

Use this to update an already opened SYSLEVEL file.

It returns the following values:
 0     NO_ERROR
 6     ERROR_INVALID_HANDLE
 19    ERROR_WRITE_PROTECT
 29    ERROR_WRITE_FAULT
 87    ERROR_INVALID_PARAMETER
 122   ERROR_INSUFFICIENT_BUFFER
When it returns ERROR_INSUFFICIENT_BUFFER, *pulSize contains the minimum requested size.

=== ulBufSize - input ===
The length, in bytes, of pBuffer. This is the number of bytes to be read or write.

=== phFile - output ===
Address of the handle for the file.

=== pszCID - input ===
It's the component ID string. It's required when you specify the OLF_CHECKID flag when opening a syslevel flag. It's a nine-digit string, not null-terminated, which uniquely identifies the component in conjunction with pszName. That is, you can have multiple SYSLEVEL files with the same name, but you can't have multiple syslevel files with the same name and ID.

If you are not using the OLF_CHECKID flag, set pszCID to NULL.

== RexxLvl() ==
[Images:rexx-lvl.gif]

RexxLvl returns a string describing the state of, or the result of an operation upon, a SYSLEVEL file. This function is used to request information on the state of a SYSLEVEL file, or to carry out some specific operation on the SYSLEVEL file.

The first argument can be one of the following strings (of which only the first letter is needed) which describes the action to be carried out:

;"c[lose]"
:closes the specified syslevel file. File is a filename returned by a previous RexxLvl OPEN or NEW call.

;"e[num]"
:enumerates the matching SYSLEVEL files. Extension is (an optional) SYSLEVEL file extension.  Id is (an optional) component ID. It returns the number of matching files, or 'ERROR'. The corresponding filenames are pushed on the current queue. Use PULL or PARSE PULL to get them back.

;"n[ew]"
:creates a new SYSLEVEL file, in the current directory. Extension is the SYSLEVEL file extension, and id is the component ID. It returns a file name to be used by subsequent RexxLvl calls.

;"o[pen]"
:opens the specified SYSLEVEL file. Extension is the SYSLEVEL file extension, and id is the component ID. It returns a file name to be used by subsequent RexxLvl calls, 'NOTFOUND' if the required file was not found or 'ERROR' if an error occurred while searching.

Note: It returns the first matching SYSLEVEL file.

;"q[uery]"
:queries a SYSLEVEL file field. File is a filename returned by a previous RexxLvl OPEN or NEW call. Field is the field to be queried. It can be any of the following (of which only the first letter is needed):

;"n[ame]"
:component name. Its length cannot exceed 79 characters.

;"i[d]"
:component ID. It's a nine-digit string.

;"k[ind]"
:component kind. It can be 0 (if the component is a base one), 1 or 2 (if the component is a system extension) or 15 otherwise.

;"v[ersion]"
:component version. It should follows the 'x.yy[.z]' format.

;"t[ype]"
:component type. It's a string.

;"c[csd]"
:current CSD level. It's a seven-byte string.

;"p[csd]"
:previous CSD level. It's a seven-byte string. It returns the field value or 'ERROR'.

;"s[et]"
:sets the specified SYSLEVEL file field. File is a filename returned by a previous RexxLvl OPEN or NEW call. Field is the field to be set. It can be any of the values taken by the field parameter of the RexxLvl "query" call, except "p[csd]" (you can't set the "p[csd]" field's
value - it is automatically sets when you update the c[csd] field). Value is the field's new value. It returns an empty string, or 'ERROR'.

== LvlQueryLevelFile ==
 APIRET LvlQueryLevelFile(PSZ pszName, PSZ pszCID, PVOID pBuffer, ULONG ulBufSize)

Use this to query/find existing SYSLEVEL files. This function enumerates all the SYSLEVEL files present in the system and returns the names as a list in the pBuffer parameter. Each SYSLEVEL file name is terminated with a NULL character and the last name is terminated with two successive NULL characters. Specifying pszName or pszCID (or both) restricts the
enumeration to the corresponding SYSLEVEL files.

It returns the following values:
 0     NO_ERROR
 87    ERROR_INVALID_PARAMETER
 122   ERROR_INSUFFICIENT_BUFFER

When it returns ERROR_INSUFFICIENT_BUFFER, the first ulBufSize bytes of pBuffer are correctly filled.

[[Category:Languages Articles]]