NAME

VMS::CMS - Perl extension for access to the CMS Code Management System

SYNOPSIS

use VMS::CMS;

DESCRIPTION

This module provides access to the Code Management System (CMS) software using its callable interface.

Most routines will return a true value if successful or undef instead of the return value documented below if the underlying CMS routine returns a failure status. In this case, the CMS status can be found in $^E.

EXPORT

None by default.

Exportable constants

CMS_K_ACCEPT CMS_K_ACL_CLASS CMS_K_ACL_COMMAND
CMS_K_ACL_ELEMENT CMS_K_ACL_GROUP CMS_K_ACL_LIBRARY
CMS_K_AFTER CMS_K_BEFORE CMS_K_CANCEL CMS_K_MARK CMS_K_REJECT
CMS_K_REVIEW CMS_K_SUPERSEDE CMS_M_ELEMENT_DIF
CMS_M_GENERATIONAL_DIF CMS_M_IGNORE_CASE
CMS_M_IGNORE_FIRST_VARIANT CMS_M_IGNORE_FORM
CMS_M_IGNORE_HISTORY CMS_M_IGNORE_LEAD CMS_M_IGNORE_NOTES
CMS_M_IGNORE_SPACE CMS_M_IGNORE_TRAIL CMS_M_VARIANT_DIF
CMS__ABSTIM CMS__ACCEPTANCES CMS__ACCEPTED CMS__ACCVIORD
CMS__ACCVIOWT CMS__ALL CMS__ALPHACHAR CMS__ALRDYEXISTS
CMS__ALRDYINCLS CMS__ALRDYINGRP CMS__ALRDYMARKED
CMS__ANNOTATED CMS__ANNOTATIONS CMS__ANNSIGNAL
CMS__ARGCONFLICT CMS__ARGCOUNTERR CMS__AUTOREC
CMS__AUTORECSUC CMS__BADBUG CMS__BADCALL CMS__BADCRC
CMS__BADCRETIME CMS__BADFORMAT CMS__BADLENSTR CMS__BADLIB
CMS__BADLST CMS__BADLSTSTR CMS__BADORDSTR CMS__BADPTR
CMS__BADREF CMS__BADREFHDR CMS__BADSTRING CMS__BADTYPSTR
CMS__BADVERSION CMS__BADVERSTR CMS__BCKPTRSTR CMS__BUG
CMS__CANCELATIONS CMS__CANCELED CMS__CLASSGENEXP
CMS__CMPSIGNAL CMS__CNTSTR CMS__COMPARED CMS__CONCLS
CMS__CONCURRENT CMS__CONELE CMS__CONFIRM CMS__CONFLICTS
CMS__CONGRP CMS__CONHIS CMS__CONRES CMS__CONTROLC
CMS__CONVERTED CMS__CONVERTLIB CMS__CONVNOTNEC CMS__COPIED
CMS__COPIES CMS__CREATED CMS__CREATES CMS__DEFAULTDIR
CMS__DELETED CMS__DELETIONS CMS__DIFFCLASS CMS__DIFFERENT
CMS__DUPEDF CMS__DUPREF CMS__EDFINWRONGDIR CMS__EDFMISS
CMS__ELEEXISTS CMS__ELEEXP CMS__ELEMULTRES CMS__ELEXPIGN
CMS__ENDOFLIST CMS__ENDPTRSTR CMS__EOF CMS__ERRACCEPTANCES
CMS__ERRANNOTATIONS CMS__ERRCANCELATIONS CMS__ERRCLOSE
CMS__ERRCOPIES CMS__ERRCREATES CMS__ERRDELETIONS
CMS__ERRELEHIS CMS__ERREMOVALS CMS__ERREPLACEMENTS
CMS__ERRESERVATIONS CMS__ERRETRIEVALS CMS__ERRFETCHES
CMS__ERRGENDELETIONS CMS__ERRHISLINE CMS__ERRINSERTIONS
CMS__ERRMARKS CMS__ERRMODACLS CMS__ERRMODIFIES CMS__ERRPAREXP
CMS__ERRREJECTIONS CMS__ERRREVIEWS CMS__ERRUNRESERVES
CMS__ERRVER2 CMS__ERRVERARC CMS__ERRVERCLS CMS__ERRVERCMD
CMS__ERRVERCON CMS__ERRVEREDFS CMS__ERRVERELE CMS__ERRVERFRE
CMS__ERRVERGEN CMS__ERRVERGRP CMS__ERRVERREFS CMS__ERRVERRES
CMS__ERRVERSTR CMS__EXCLUDE CMS__EXIT CMS__EXTENDEDLIB
CMS__EXTFOUND CMS__FACILITY CMS__FETCHED CMS__FETCHES
CMS__FILEXISTS CMS__FILINUSE CMS__FIXCRC CMS__FIXHDR
CMS__FREBLKCON CMS__GENCREATED CMS__GENDELETED
CMS__GENDELETIONS CMS__GENEXISTS CMS__GENINSERTED
CMS__GENMULTRES CMS__GENNOINSERT CMS__GENNOREMOVE
CMS__GENNOTANC CMS__GENNOTFOUND CMS__GENNOTRES
CMS__GENRECSIZE CMS__GENREMOVED CMS__GENRESREV
CMS__GENTOODEEP CMS__GROUPEXP CMS__HASFILES CMS__HASMEMBERS
CMS__HISNOTSTM CMS__HISTDEL CMS__IDENTCLASS CMS__IDENTICAL
CMS__IDENTNOTRES CMS__ILLACT CMS__ILLARCREC CMS__ILLCHAR
CMS__ILLCLSNAM CMS__ILLCONREC CMS__ILLDATREC CMS__ILLEGALDEV
CMS__ILLELENAM CMS__ILLELEXP CMS__ILLFORMAT CMS__ILLGEN
CMS__ILLGRPNAM CMS__ILLHIST CMS__ILLNAME CMS__ILLNOTE
CMS__ILLOBJTYP CMS__ILLPAR CMS__ILLPOSVAL CMS__ILLREFDIR
CMS__ILLRMK CMS__ILLSEQ CMS__ILLSUBTYP CMS__ILLVAR
CMS__INCLIBVER CMS__INCRANGSPEC CMS__INSERTED CMS__INSERTIONS
CMS__INUSE CMS__INVFETDB CMS__INVFIXMRS CMS__INVGENLRL
CMS__INVLENGTH CMS__INVLIBDB CMS__INVOKERBK CMS__INVSTRDES
CMS__ISMEMBER CMS__ISRESERVED CMS__LIBALRINLIS CMS__LIBINSLIS
CMS__LIBIS CMS__LIBLISMOD CMS__LIBLISNOTMOD CMS__LIBNOTINLIS
CMS__LIBREMLIS CMS__LIBSET CMS__LONGVARFOUND CMS__MANCONLIB
CMS__MARKED CMS__MARKS CMS__MAXARG CMS__MERGECONFLICT
CMS__MERGECOUNT CMS__MERGED CMS__MINARG CMS__MISBLKSTR
CMS__MISMATCON CMS__MODACL CMS__MODACLS CMS__MODIFICATIONS
CMS__MODIFIED CMS__MSGBUILD CMS__MSGCANCEL CMS__MSGCONTINUE
CMS__MSGPOST CMS__MSGUPDATE CMS__MSSBLKSTR CMS__MULTCALL
CMS__MULTPAR CMS__MUSTBEDIR CMS__MUSTBEFIL CMS__MUSTBEPOS
CMS__MUTEXC CMS__NEEDNUMBER CMS__NEEDPERIOD CMS__NETNOTALL
CMS__NOACCEPT CMS__NOACCESS CMS__NOACE CMS__NOALTDELETE
CMS__NOANNOTATE CMS__NOBACKUP CMS__NOBCKPTR CMS__NOCANCEL
CMS__NOCHANGES CMS__NOCLOSE CMS__NOCLS CMS__NOCMD
CMS__NOCOMMALIST CMS__NOCOMPARE CMS__NOCONCUR CMS__NOCONFIRM
CMS__NOCONRES CMS__NOCONVERT CMS__NOCOPY CMS__NOCREATE
CMS__NODEFACL CMS__NODELACCESS CMS__NODELETE CMS__NODELETIONS
CMS__NODELFUTURE CMS__NODELGEN1 CMS__NOEDFIWDREPAIR
CMS__NOELE CMS__NOELEENT CMS__NOERRLOG CMS__NOEXTENDED
CMS__NOEXTENDEDREF CMS__NOFETCH CMS__NOFILE CMS__NOGENBEFORE
CMS__NOGENDELETED CMS__NOGENS CMS__NOGRP CMS__NOHIS
CMS__NOHISNOTES CMS__NOHISPAR CMS__NOINPUT CMS__NOINSERT
CMS__NOMARK CMS__NOMATCH CMS__NOMODACL CMS__NOMODARG
CMS__NOMODIFY CMS__NOMOREPARAM CMS__NOOBJ CMS__NOOBJTYP
CMS__NORECOVER CMS__NOREF CMS__NOREFDIR CMS__NOREFELE
CMS__NOREJECT CMS__NOREMARK CMS__NOREMOVAL CMS__NOREPAIR
CMS__NOREPBCKPTR CMS__NOREPCMD CMS__NOREPEDF CMS__NOREPGENLRL
CMS__NOREPGENMRS CMS__NOREPLACE CMS__NOREPREF CMS__NOREPRO
CMS__NOREPSEQDATA CMS__NORES CMS__NORESERVATION
CMS__NORESNOCON CMS__NORESRO CMS__NORETRIEVE CMS__NOREV
CMS__NOREVIEW CMS__NOREVPEND CMS__NOREVSPEND CMS__NORMAL
CMS__NOSINCE CMS__NOSRCHLST CMS__NOSUPERSEDE CMS__NOTBYCMS
CMS__NOTCMSLIB CMS__NOTCOMPLETED CMS__NOTCRELIB
CMS__NOTDIRDES CMS__NOTESVALREQ CMS__NOTFOUND CMS__NOTLOGGED
CMS__NOTNOREF CMS__NOTRESBYOU CMS__NOTSET CMS__NOTTHERE
CMS__NOTWILD CMS__NOUNRESERVE CMS__NOVERIFY CMS__NOWLDCARD
CMS__NULLARG CMS__NULLSTR CMS__NUMGENEXP CMS__OLDSYNTAX
CMS__ONEPERIOD CMS__OPENARC CMS__OPENIN CMS__OPENIN1
CMS__OPENIN2 CMS__OPENOUT CMS__OVERDRAFT CMS__POSVALREQ
CMS__PROCEEDING CMS__QUALCONFLICT CMS__READERR CMS__READIN
CMS__READONLY CMS__RECGRP CMS__RECNOTNEC CMS__RECOVERED
CMS__REFMISMAT CMS__REFMISS CMS__REFREPAIR CMS__REJECTED
CMS__REJECTIONS CMS__REMARK CMS__REMOVALS CMS__REMOVED
CMS__REPAIRED CMS__REPBADLST CMS__REPBADTYP CMS__REPBCKPTR
CMS__REPCMD CMS__REPCNTSTR CMS__REPDEL CMS__REPEDF
CMS__REPENDPTR CMS__REPGENLRL CMS__REPGENMRS
CMS__REPILLDATREC CMS__REPLACEMENTS CMS__REPMISBLK
CMS__REPREF CMS__RESERVATIONS CMS__RESERVED
CMS__RESERVEDBYYOU CMS__RETRIEVALS CMS__RETRIEVED
CMS__REVIEWED CMS__REVIEWS CMS__REVPENDING CMS__SAMELINE
CMS__SEQFAIL CMS__SEQMISMAT CMS__SEQUENCED CMS__SIZEMISMAT
CMS__STARTHIS CMS__STOPPED CMS__SUPERSEDE CMS__SYSTIMDIF
CMS__SYSTIMERR CMS__TIMEORDER CMS__TOODEEP CMS__TOOLONG
CMS__TOOMANYLIBS CMS__TRUNCLST CMS__TRYAGNLAT CMS__UNDEFLIB
CMS__UNFOUT CMS__UNRECTYPE CMS__UNRESERVED CMS__UNRESERVES
CMS__UNSUPFRMT CMS__USERECOVER CMS__USEREPAIR CMS__USERERR
CMS__USESETLIB CMS__VARINRANGE CMS__VARLETTER CMS__VER2
CMS__VERARC CMS__VERCLS CMS__VERCMD CMS__VERCON CMS__VEREDF
CMS__VEREDFERR CMS__VEREDFS CMS__VERELE CMS__VERFRE
CMS__VERGRP CMS__VERIFIED CMS__VERILLDATREC CMS__VERLMTERR
CMS__VERREF CMS__VERREFERR CMS__VERREFERRW CMS__VERREFS
CMS__VERRES CMS__VERSTR CMS__WAITING CMS__WILDCONFLICT
CMS__WILDMATCH CMS__WILDNEEDED CMS__WILDNOMATCH CMS__WILDVER
CMS__WRITEERR CMS__ZEROADD CMS__ZLENBLK

Functions

show_version

Returns a reference to a hash containing information about the installed version of CMS.

my $hashref = VMS::CMS::show_version;
print "CMS version $hashref->{BRIEF} is installed\n";

The hash will contain the following attributes.

BRIEF

A short string containing the version of CMS, e.g., 'V4.2'.

FULL

A longer string containing the product name and version, e.g. 'CMS Version V4.2'.

ABSOLUTE

The monotonic version number for the installed CMS release, e.g., 100205.

get_messages

The callable CMS routines send various status messages to the calling code using VMS signalling. Many of these routines allow the caller to provide a callback routine to intercept and handle these messages.

The get_messages routine returns the messages generated by the last call to a CMS routine that provides this capability. The messages are returned in a reference to an array of strings.

my $arrayref = VMS::CMS::get_messages;

get_message_details

Similar to get_messages but returns a list of unformatted messages with the arguments to those messages. This is useul for finding out details of exactly what CMS did, such as file names acted upon, generations created, etc.

$l->replace($element,{REMARK=>$text});
$m = VMS::CMS::get_message_details;
$newgen = $m->[0]{Args}[0];

Each hashref in the list will contain the following elements:

MessageId

The status code.

Message

The raw message text.

Args

An reference to an array containing the arguments to the FAO directives in the message text.

transaction_mask

Returns an integer that can be used to specify a set of transactions to select for delete_history or show_history.

my $int = VMS::CMS::transaction_mask(qw(CREATE INSERT DELETE));

Recognized transactions include COPY, CREATE, DELETE, FETCH, INSERT, MODIFY, REMARK, REMOVE, REPLACE, RESERVE, UNRESERVE, VERIFY, SET ACL, ACCEPT, CANCEL, MARK, REJECT and REVIEW.

new

Returns a blessed reference to a library descriptor block. This object can be used to invoke other routines.

my $ldb = VMS::CMS::new;

Library Access Routines

These routines can be used to create, access, or modify CMS libraries.

create_library

Creates a new CMS library in the directory specified. Returns a CMS status code if the operation is successful.

my $sts = $ldb->create_library($path,{option=>value,...});
die "CMS create library failed with status $^E\n"
    unless ($sts);

$path specifies an empty directory CMS should use to build the new library. $remark is a string to be logged in the history. The following options are recognized.

REFERENCE_COPY

Specifies a directory to contain reference copies of elements in the library.

CREATE

Boolean value that tells CMS to create missing directories. By default, the directories must already exist.

KEEP

By default, CMS deletes files after storing them in the library. To change the default for all files stored in this library, set KEEP to true.

REVISION_TIME

Boolean value telling CMS to use the file's last revision time (0) or its storage time (1).

CONCURRENT

Boolean value that indicates whether concurrent reservations should be allowed. The default is true.

EXTENDED_NAMES

On systems running versions of VMS that support extended filenames, set this option to allow CMS to use this support.

POSITION

Used with the PATH option to specify where in the current search list of CMS libraries the new library should be placed. Valid values are SUPERSEDE (default), BEFORE or AFTER. If BEFORE or AFTER is specified but the PATH option is not, the library will be inserted at the beginning or end, respectively, of the current search list.

PATH

Specifies an CMS library path already in the CMS library search list.

REMARK

A string to save as the creation remark for the new library.

set_library

$ldb->set_library($path,{option=>value});

POSITION

Used with the PATH option to specify where in the current search list of CMS libraries the new library should be placed. Valid values are SUPERSEDE (default), BEFORE or AFTER. If BEFORE or AFTER is specified but the PATH option is not, the library will be inserted at the beginning or end, respectively, of the current search list.

PATH

Specifies an CMS library path already in the CMS library search list.

VERIFY

A boolean requesting that CMS verify the library before proceding.

set_nolibrary

Removes a library from or clears the library search list.

$sts = $ldb->set_nolibrary([$path]);

modify_library

Changes attributes of a library.

$sts = $ldb->modify_library({option=>value});

Available options:

REMARK

Specifies a remark to store in the history with this command.

REFERENCE_COPY

Specifies a directory to contain reference copies of elements in the library.

KEEP

By default, CMS deletes files after storing them in the library. To change the default for all files stored in this library, set KEEP to true.

REVISION_TIME

Boolean value telling CMS to use the file's last revision time (0) or its storage time (1).

CONCURRENT

Boolean value that indicates whether concurrent reservations should be allowed. The default is true.

EXTENDED_NAMES

On systems running versions of VMS that support extended filenames, set this option to allow CMS to use this support.

remark

Adds a remark to the library history.

sts = $ldb->remark($remark,{option=>value});

Options:

UNUSUAL

Boolean indicating that this is an unusual remark.

show_history

Returns history information.

my $arrayref = $ldb->show_history({option=>value});

Options:

OBJECT_NAME

USER

BEFORE

SINCE

TRANSACTION_MASK

Returns a reference to an array of hashes. Each hash contains the following information:

COMMAND

OBJECT

USER

REMARK

TRANSACTION_TIME

UNUSUAL

show_library

Returns a reference to a hash that contains information about a CMS library.

my $hashref = $ldb->show_library({option=>value});

Options:

VERIFY

A boolean requesting that CMS verify the library before proceding.

Information returned:

REFERENCE_COPY

Indicates the directory used for reference copies if enabled.

ELEMENTS

Contains the number of elements stored in the library.

GROUPS

Contains the number of groups defined in the library.

CLASSES

Contains the number of classes defined in the library.

RESERVATIONS

Contains the number of elements currently reserved from the library.

CONCURRENT

Indicates whether concurrent reservations are allowed from the library.

REVIEWS_PENDING

Indicates the number of generations requiring review.

show_reservations

Returns a reference to a list of elements currently reserved from the library.

my $res = $ldb->show_reservations({option=>value});

Options:

ELEMENT

Limits the list to elements matching the provided element expression.

GENERATION

Limits the list to generations matching the specified generation expression.

USER

Limits the list to elements reserved by the specified user.

IDENTIFICATION

Limits the list to reservations having the specified identification.

The returned list will contain references to hashes containing the following attributes.

ELEMENT

The element name.

GENERATION

The generation of the element that is reserved.

TIME

The time that the element was reserved.

USER

The user that reserved the element.

REMARK

The remark entered when the element was reserved.

CONCURRENT

Indicates concurrent reservation status. -1 indicates a concurrent replacement, 0 indicates a current reservation, 1 indicates a concurrent reservation.

MERGE_GENERATION

Indicates a generation that was merged with the reserved generation.

NONOTES

True if notes were supressed.

NOHISTORY

True if history was supressed.

ACCESS

Indicates whether concurrent accesses are allowed. 0 indicates that concurrent reservations are allowed. 1 indicates that they are not allowed. 2 indicates that the current reservation does not allow concurrent reservations.

Element Access Routines

These routines provide access to files stored in a CMS library.

create_element

$sts = $ldb->create_element($element, {option=>value});

Options:

HISTORY

NOTES

INPUT_FILE

POSITION

KEEP

RESERVE

CONCURRENT

REFERENCE_COPY

REVIEW

REMARK

delete_element

differences

$sts = $ldb->differences({option=>value});

Options:

FILENAME1

GENERATION1

FILENAME2

GENERATION2

OUTPUT_FILE

OUTPUT_ROUTINE

A reference to a subroutine to call for each line of output. The subroutine is passed one or two arguments. The first is a hash containing the output record and some flags. The second argument is the value of option USER_ARG, if specified.

The hash passed to the subroutine contains the following values.

OUTPUT_RECORD

FIRST_CALL

EOF

USER_ARG

An argument to pass to the subroutine pass to OUTPUT_ROUTINE.

NOOUTPUT

PARALLEL

FULL

WIDTH

PAGE_BREAK

APPEND

FORMAT

IGNORE

SKIP_LINES

BEGIN_SENTINAL

END_SENTINAL

REMARK

fetch

Retrieves and optionally reserves an element from the library.

$sts = $ldb->fetch($element,{option=>value})

Options:

REMARK

GENERATION

MERGE_GENERATION

OUTPUT_FILE

HISTORY

NOTES

RESERVE

NOHISTORY

CONCURRENT

NOOUTPUT

POSITION

modify_element

remove_element

replace

$sts = $ldb->replace($element, {option=>value});

Options:

VARIANT

INPUT_FILE

GENERATION

RESERVE

KEEP

IF_CHANGED

IDENTIFICATION

REMARK

show_element

Returns a reference to an array of hash references. Each hash contains information about one matching element.

$array_ref = $ldb->show_element({option=>value})

Options:

ELEMENT

MEMBERS

The following information is returned for each element.

ELEMENT

REMARK

HISTORY

NOTES

POSITION

CONCURRENT

REFERENCE_COPY

GROUP_LIST

REVIEW

unreserve

Group Access Routines

These routines provide access to element groups defined in a CMS library.

create_group

$sts = $ldb->create_group($group, {option=>value});

delete_group

$sts = $ldb->delete_group($group, {option=>value});

insert_element

$sts = $ldb->insert_element($element, $group, {option=>value});

Options:

REMARK

IF_ABSENT

REMARK

insert_group

$sts = $ldb->insert_group($subgroup, $group, {option=>value});

Options:

REMARK

IF_ABSENT

modify_group

remove_element

remove_group

show_group

$arrayref = $ldb->show_group({option=>value});

Options:

GROUP

CONTENTS

Returns a reference to an array of hashes containing:

GROUP

REMARK

READ_ONLY

LEVEL

CONTENTS

Generation Access Routines

These routines provide access to generations of elements defined in a CMS library.

delete_generation

modify_generation

review_generation

show_generation

$arrayref = $ldb->show_generation({option=>value});

Options:

ELEMENT

GENERATION

FROM_GENERATION

ANCESTORS

DESCENDANTS

MEMBERS

BEFORE

SINCE

Returns a reference to an array of hashes containing:

ELEMENT

GENERATION

USER

REMARK

CLASS_LIST

FORMAT

ATTRIBUTES

TRANSACTION_TIME

CREATION_TIME

REVISION_TIME

REVISION

RESERVATIONS

RECORD_SIZE

REVIEW_STATUS

show_reviews_pending

Class Access Routines

These routines provide access to classes defined in a CMS library.

create_class

$sts = $ldb->create_class($class, {option=>value});

delete_class

$sts = $ldb->delete_class($class, {option=>value});

insert_generation

$sts = $ldb->insert_generation($element, $class, {option=>value});

Options:

REMARK

GENERATION

ALWAYS

SUPERSEDE

IF_ABSENT

modify_class

remove_generation

show_class

my $arrayref = $ldb->show_class({option=>value});

Options:

CLASS

Returns a reference to an array of hashes containing:

CLASS

REMARK

READ_ONLY

SEE ALSO

See the VMS/CMS documentation including the Callable Routines Reference Manual.

AUTHOR

Thomas Pfau, <tfpfau@gmail.com<gt>

COPYRIGHT AND LICENSE

Copyright (C) 2008,2010,2011,2012 by Thomas Pfau.

This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0.

This module is distributed in the hope that it will be useful but it is provided "as is"and without any express or implied warranties.

cpanm VMS::CMS

perl -MCPAN -e shell
install VMS::CMS