The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
BS2000-LMS-0.08
River stage zero No dependents
++
/ BS2000::LMS

NAME

BS2000::LMS - Perl extension for library access under BS2000

SYNOPSIS

  use BS2000::LMS;

  $library = new BS2000::LMS '$.SYSLIB.CRTE';
  print $_->{type}, ' ', $_->{name}, "\n"
    foreach ($library->list(type => 'S', name => 'CSTD*'));

ABSTRACT

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.

DESCRIPTION

Access to BS2000 libraries in Perl is implemented using accessor objects.

See the different METHODS for details.

EXPORT

Several constants originating in the BS2000 system include lms.h are exported. They are put into the following groups:

:returncodes

for all possible return codes LMSUP_OK, LMSUP_TRUNC, LMSUP_EOF, LMSUP_LMSERR, LMSUP_PARERR, LMSUP_SEQERR and LMSUP_INTERR

:storage_form

for the different storage forms (full and delta) LMSUP_FULL and LMSUP_DELTA

:hold_state

for the source code control states LMSUP_FREE and LMSUP_INHOLD

An additional group :all gives you access to all, so if you type

  use BS2000::LMS qw(:all);

you may use any of them.

METHODS

new - create a new LMS accessor object

    $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)

name

the name of the library if it is not accessed by link name (empty otherwise)

return_code

the last return code set by a call to the LMS API (see also the method rc_message described later)

plam_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)

lms_message

the last LMS message set by a call to the LMS API (see also the methods message and rc_message described later)

dms_message

the last DMS message set by a call to the LMS API (see also the methods message and rc_message described later)

lms_version

the version of the LMS API used

message - return string containing the last messages set

    $last_message = $accessor_object->message();

Example:

    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.

rc_message - return string with last return code / messages

    $last_message = $accessor_object->rc_message();

Example:

    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.

list - return array of library elements (table of contents)

    @toc = $accessor_object->list(%selection_hash);

Example:

    @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:

type

to select a specific type of library element, e.g. 'S' for source elements

name

to select elements with a specific name

version

to select elements with a specific version, use '~' for latest???

user_date

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

  • a range using <YYYY-MM-DD:YYYY-MM-DD>*

Note that you must add the trailing * as a julian day may follow the "normal" date.

user_time

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>*.

creation_date

to select elements with a specific creation date (see user_date for details of the format)

creation_time

to select elements with a specific creation time (see user_time for details of the format)

modification_date

to select elements with a specific modification date (see user_date for details of the format)

modification_time

to select elements with a specific modification time (see user_time for details of the format)

access_date

to select elements with a specific access date (see user_date for details of the format)

access_time

to select elements with a specific access time (see user_time for details of the format)

mode_set

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.

mode_unset

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.

Example:

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.

NOTE: Both mode_set and mode_unset only work, if protection flags are actually used for an element. Otherwise the element is always selected!

hold_state

to select elements with a specific hold state ('-' for free, 'H' for held)

min_element_size

to select elements with a specific minimal element size (in PAM pages = 2K)

max_element_size

to select elements with a specific maximal element size (in PAM pages = 2K)

from_index

shorten the result to a sublist starting with this index

to_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):

type

the type of the library element, e.g. 'S' for source elements

name

the (main) name of the element

version

the version number of the element (An element may be included in a library more than once with different version numbers!)

storage_form

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

secondary_name

a secondary reference name for the element

secondary_attribute

a secondary ??? name for the element???

user_date

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)

user_time

a specific time set for this element by some user of the form HH:MM:SS

creation_date

the creation date of an element (see user_date for details of the format)

creation_time

the creation time of an element

modification_date

the date of the last modification of an element (see user_date for details of the format)

modification_time

the time of the last modification of an element

access_date

the date of the last access to an element (see user_date for details of the format)

access_time

the time of the last access to an element

mode

the (unix like) protection mode of the element (this is translated from the various BS2000 protection flags)

hold_state

the hold state of the element (LMSUP_FREE respective '-' for free and LMSUP_INHOLD respective 'H' for held)

holder

the user ID of the holder (only valid if hold_state is held)

element_size

the size of the element in PAM pages of 2 KB

ToDo: Parameter-Checks???

add - add an element to the library

    $bytes_added = $accessor_object->add($input_file, %element_info);

Example:

    $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):

type

the type of the element, e.g. 'S' for a source element (mandatory)

name

the name of the element (mandatory)

version

the version of the element

user_date

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).

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.

extract - extract an element from the library

    $bytes_extracted = $accessor_object->extract($output_file,
                                                 %element_descriptor);

Example:

    $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:

type

the type of the element, e.g. 'S' for a source element

name

the name of the element

version

the version of the element (this is an optional attribute, the default is '*HIGH' for the newest version)

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?).

KNOWN BUGS

The functionality is still limited to a few methods.

SEE ALSO

the Fujitsu-Siemens documentation Library Management System, Subroutine Interface (LMS_UPS.PDF, search on http://www.fujitsu-siemens.com)

AUTHOR

Thomas Dorner <Thomas.Dorner@start.de> or <Thomas.Dorner@gmx.de>

COPYRIGHT AND LICENSE

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.