BS2000::LMS - Perl extension for library access under BS2000
use BS2000::LMS; $library = new BS2000::LMS '$.SYSLIB.CRTE'; print $_->{type}, ' ', $_->{name}, "\n" foreach ($library->list(type => 'S', name => 'CSTD*'));
This module is a Perl extension to access BS2000 libraries using the LMS API (Library Maintenance System, Subroutine Interface). It is only useful for the BS2000 port of Perl.
Access to BS2000 libraries in Perl is implemented using accessor objects.
See the different METHODS for details.
Several constants originating in the BS2000 system include lms.h are exported. They are put into the following groups:
lms.h
for all possible return codes LMSUP_OK, LMSUP_TRUNC, LMSUP_EOF, LMSUP_LMSERR, LMSUP_PARERR, LMSUP_SEQERR and LMSUP_INTERR
LMSUP_OK
LMSUP_TRUNC
LMSUP_EOF
LMSUP_LMSERR
LMSUP_PARERR
LMSUP_SEQERR
LMSUP_INTERR
for the different storage forms (full and delta) LMSUP_FULL and LMSUP_DELTA
LMSUP_FULL
LMSUP_DELTA
for the source code control states LMSUP_FREE and LMSUP_INHOLD
LMSUP_FREE
LMSUP_INHOLD
An additional group :all gives you access to all, so if you type
:all
use BS2000::LMS qw(:all);
you may use any of them.
$accessor_object = new BS2000::LMS $library_name [, $is_linkname_flag ]; or $accessor_object = BS2000::LMS->new($library_name [, $is_linkname_flag ]);
Example:
$library = new BS2000::LMS '$.SYSLIB.CRTE'; or $library = BS2000::LMS->new('LIBLINK1', 1);
This is the constructor for a a new LMS accessor object. The first parameter is the mandatory name of the library. If the first parameter should specify a BS2000 link name, the optional second parameter must be set to true.
An accessor object contains the following important elements:
the link name if the library is accessed by link name (empty otherwise)
the name of the library if it is not accessed by link name (empty otherwise)
the last return code set by a call to the LMS API (see also the method rc_message described later)
rc_message
the last PLAM (program library access method) message set by a call to the LMS API (see also the methods message and rc_message described later)
message
the last LMS message set by a call to the LMS API (see also the methods message and rc_message described later)
the last DMS message set by a call to the LMS API (see also the methods message and rc_message described later)
the version of the LMS API used
$last_message = $accessor_object->message();
warn $library->message();
This method returns a string with the message codes of the last call to the LMS subprogram library. Only message codes different from 0 are included.
$last_message = $accessor_object->rc_message();
warn $library->rc_message();
This method returns a string with the return code and the message codes of the last call to the LMS subprogram library. Only message codes different from 0 are included.
@toc = $accessor_object->list(%selection_hash);
@toc = $library->list(type => 'S', name => 'CSTD*'); print $_->{type}, ' ', $_->{name}, "\n" foreach (@toc);
This method returns an array of elements of the table of contents of the library (or an undef in case of errors). Each element in this array is a reference to a hash holding an attribute of the library element (see below). The optional parameters of the method are used to select specific elements of the whole table of contents. They are:
undef
to select a specific type of library element, e.g. 'S' for source elements
'S'
to select elements with a specific name
to select elements with a specific version, use '~' for latest???
'~'
to select elements with a specific date set by some user. You may use:
a single date using the format YYYY-MM-DD* with / (single character) or * (any characters) as wildcards anywhere in the string
YYYY-MM-DD*
/
*
a range using <YYYY-MM-DD:YYYY-MM-DD>*
<YYYY-MM-DD:YYYY-MM-DD>*
Note that you must add the trailing * as a julian day may follow the "normal" date.
to select elements with a specific time set by some user. You may use / and * as wildcards but you can't use a : anywhere in this string! In addition you may use an hourly range of <HH:HH>*.
:
<HH:HH>*
to select elements with a specific creation date (see user_date for details of the format)
to select elements with a specific creation time (see user_time for details of the format)
to select elements with a specific modification date (see user_date for details of the format)
to select elements with a specific modification time (see user_time for details of the format)
to select elements with a specific access date (see user_date for details of the format)
to select elements with a specific access time (see user_time for details of the format)
to select elements with a specific (unix like) protection mode (this is translated into the various BS2000 protection flags). Only set bits are checked, the protection for unset bits is ignored.
to select elements with a specific (unix like) protection mode (this is translated into the various BS2000 protection flags). This is the inverse of mode_set. Only unset bits are checked, the protection for set bits is ignored.
mode_set
If you want to select elements which may be read, but not executed by members of the user group, you would write:
$library->list(mode_set => 040, mode_unset => 010);
If both mode_set and mode_unset refer to a specific bit, mode_unset is used.
mode_unset
NOTE: Both mode_set and mode_unset only work, if protection flags are actually used for an element. Otherwise the element is always selected!
to select elements with a specific hold state ('-' for free, 'H' for held)
'-'
'H'
to select elements with a specific minimal element size (in PAM pages = 2K)
to select elements with a specific maximal element size (in PAM pages = 2K)
shorten the result to a sublist starting with this index
shorten the result to a sublist ending with this index
In all selection strings / (single character) and * (any string including an empty one) may be used as wildcards, unless specified otherwise.
A library element in the result (a reference to a hash) is described by the following attributes (each attribute is a key of the hash):
the type of the library element, e.g. 'S' for source elements
the (main) name of the element
the version number of the element (An element may be included in a library more than once with different version numbers!)
the storage form of the element, that is LMSUP_DELTA ('D') for a delta and LMSUP_FULL ('V') (german 'voll') for an element stored as it is
'D'
V'
a secondary reference name for the element
a secondary ??? name for the element???
a specific date set for this element by some user of the form YYYY-MM-DDjjj (jjj is the optional julian day of the year)
a specific time set for this element by some user of the form HH:MM:SS
the creation date of an element (see user_date for details of the format)
the creation time of an element
the date of the last modification of an element (see user_date for details of the format)
the time of the last modification of an element
the date of the last access to an element (see user_date for details of the format)
the time of the last access to an element
the (unix like) protection mode of the element (this is translated from the various BS2000 protection flags)
the hold state of the element (LMSUP_FREE respective '-' for free and LMSUP_INHOLD respective 'H' for held)
the user ID of the holder (only valid if hold_state is held)
the size of the element in PAM pages of 2 KB
ToDo: Parameter-Checks???
$bytes_added = $accessor_object->add($input_file, %element_info);
$timestamp = localtime $library->add("myinclude.h", type => 'S', name => 'myinclude.h', user_date => strftime("%Y-%m-%d", $timestamp), user_time => strftime("%H:%M:%S", $timestamp)) or die 'error adding myinclude.h: ', $library->rc_message(); $library->add(["<:encoding(ascii)", "somefile.asc"], type => 'S', name => 'somefile') or die 'error adding somefile.asc: ', $library->rc_message();
This method adds an element to the library. The element may be an existing element (which gets a new version) or a new one. $input_file may be a reference to a list which is then passed unmodified to the normal Perl open function. So (starting with Perl 5.8) any PerlIO attribute may be used to convert from a specific character set. Regardless, writing is always done using raw binary IO. This means that library elements are always in written in EBCDIC. The following attributes may be set for the element (the first two attributes are mandatory):
the type of the element, e.g. 'S' for a source element (mandatory)
the name of the element (mandatory)
the version of the element
the non-system-set-date for the element. The valid format is YYYY-MM-DD or the string "now" (localtime, this also sets user_time).
the non-system-set-time for the element. Valid formats are HH:MM:SS, HH:MM or the string "now" (localtime, this also sets user_date).
The method returns the number of bytes written or -1 in case of errors. Note that newlines are counted even though they are not really written (each line is a record), so you should get the size of the original file.
$bytes_extracted = $accessor_object->extract($output_file, %element_descriptor);
$timestamp = localtime $library->extract("myinclude.h", type => 'S', name => 'myinclude.h') or die 'error extracting myinclude.h: ', $library->rc_message(); $library->extract(["<:encoding(ascii)", "somefile.asc"], type => 'S', name => 'somefile') or die 'error extracting somefile.asc: ', $library->rc_message();
This method extracts an element from the library. $output_file may be a reference to a list which is then passed unmodified to the normal Perl open function. So (starting with Perl 5.8) any PerlIO attribute may be used to convert to a specific character set. Reading is always done using raw binary IO though. The following attributes are used to specify the element:
the type of the element, e.g. 'S' for a source element
the name of the element
the version of the element (this is an optional attribute, the default is '*HIGH' for the newest version)
'*HIGH'
The method returns the size of the element read or -1 in case of errors.
NOTE: Only elements with normal records (up to 32 KB - 4 bytes) may be extracted, elements with B-records can not be extracted (yet?).
The functionality is still limited to a few methods.
the Fujitsu-Siemens documentation Library Management System, Subroutine Interface (LMS_UPS.PDF, search on http://www.fujitsu-siemens.com)
Thomas Dorner <Thomas.Dorner@start.de> or <Thomas.Dorner@gmx.de>
Copyright 2003 by Thomas Dorner
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install BS2000::LMS, copy and paste the appropriate command in to your terminal.
cpanm
cpanm BS2000::LMS
CPAN shell
perl -MCPAN -e shell install BS2000::LMS
For more information on module installation, please visit the detailed CPAN module installation guide.