Libraries must first be assigned before they can be processed. Only when assignment has been successfully performed can members be added and/or processed.
In LMS statements, libraries are specified by means of the LIBRARY operand. There are several ways of assigning a library, all of which ultimately lead directly or indirectly to PLAM libraries:
Via a globally defined library (*STD)
Using the direct name of a PLAM library
Indirectly via a link name
Using a library list ("SYSPLAMALT-" variable)
By means of type redirection ("SYSPLAMLIB." variable)
The globally defined library is assigned by means of OPEN-LIBRARY and reset to undefined by means of CLOSE-LIBRARY. Numbers 2 - 5 of the above options can be used to define the global library.
Library lists enable alternate libraries to be specified. A library list is a list showing which libraries are to be searched for a member and in which order. Library lists can only be accessed in read mode, and are defined by means of a "SYSPLAMALT-" variable (ALT stands for ALTernate library).
The type redirection mechanism allows a standard member type to be redirected to a userdefined member type. This enables existing programs which do not allow user-defined types to nonetheless function with these types. A type redirection is defined by means of a "SYSPLAMLIB." variable. Type redirection is a central mechanism which can be used in all commands, independently of LMS.
The LMS statement SHOW-LIBRARY-STATUS provides information on the status of the libraries to be processed.
Direct name of a PLAM library
The specified file name designates a PLAM library. This specification is often used during work with LMS. Normally the specified file name does in fact indicate a file, but there are the following exceptions:
if the file name begins with "SYSPLAMALT-" and an S variable of the same name exists: this indicates a library list (see "Library assignment")
if the file name begins with "SYSPLAMLIB." and an S structure variable of the same name exists: this indicates a type redirection (see "Library assignment")
Indirectly via a link name
The name <link> specified under *LINK designates a link name. As a rule, the name is a file link name defined via /ADD-FILE-LINK, to which a PLAM library is assigned. However, the following exception applies:
if an S structure variable SYSPLAMLIB.<link> exists: this indicates a type redirection (see below).
Examples
Assigning a global library with OPEN-LIBRARY
A library is opened as a global library if it is assigned through the LMS statement OPEN-LIBRARY.
Only one global library is possible per LMS run. If a new global library is opened by a second OPEN-LIBRARY statement, the first global library is closed by an internal LMS CLOSE and the new library is considered to be the global library.
A global library may already exist or can be newly created. If a library is newly created, it must be generated with MODE=*UPDATE.
A global library is normally opened only for reading. If it is to be opened for reading and writing, the operand MODE=*UPDATE must be set in the OPEN-LIBRARY statement.
In the LMS statements a global library is addressed by LIBRARY=*STD. This value is the default in these statements so no other explicit library specification is required.
/START-LMS
//WRITE-COMMENT 'Open a global library for reading and writing'
//OPEN-LIBRARY LIBRARY = global-lib, MODE = *UPDATE ..
//WRITE-COMMENT 'Display directory of the global library'
//SHOW-ELEMENT-ATTRIBUTES ..Assigning a global library via its link name
A global library can also be assigned by means of its link name. However, when using the link name, a /ADD-FILE-LINK command must be issued before calling LMS in order to establish the link with the file name of the library.
/ADD-FILE-LINK FILE-NAME = global-lib, LINK-NAME = testlib
/START-LMS
//WRITE-COMMENT 'Open a global library via link name'
//OPEN-LIBRARY LIBRARY = *LINK(LINK-NAME = testlib) . .Assigning local libraries in a statement
By specifying one or more libraries in the data structure *LIBRARY-ELEMENT of the LIBRARY operand, the libraries are defined locally within the statement. The definition of the libraries is valid only for that statement.
/START-LMS
//WRITE-COMMENT 'Example of assignment of a local library '
//WRITE-COMMENT ' in the Statement EDIT-ELEMENT ' . .
//MODIFY-LMS-DEFAULTS TYPE=S
//EDIT-ELEMENT LIBRARY-ELEMENT(LIBRARY=local-lib,ELEMENT=test) . .Assigning a local library via its link name
A local library can also be assigned by means of its link name. However, when using the link name, a /ADD-FILE-LINK command must be issued before calling LMS in order to establish the link with the file name of the library.
/ADD-FILE-LINK FILE-NAME = local-lib, LINK-NAME = testlib
/START-LMS .
//WRITE-COMMENT 'Open a local library via link name'
//WRITE-COMMENT ' in the statement EDIT-ELEMENT ' . .
//EDIT-ELEMENT (LIBRARY = *LINK(LINK-NAME = testlib), ELEMENT=test) . .
Assigning a library from a list
Library lists enable alternate libraries to be specified. The order of the alternate libraries in the list determines the order in which they are searched for members.
When a member is sought in a library list, PLAM processes the list to first of all find a member with the desired type and name. The libraries in the list are searched in the order in which they appear until the specified member name with the associated type is found. This means that if more than one library in the list contains members with the same type and name, the member is always found in the first of these libraries; this library is called the hit library.
The version specification for the member determines which member version is selected from the hit library. So one member version in a library covers all member versions in libraries named later, and the selection process is easy to follow (see example on "Library assignment")
Library lists can only be accessed in read mode. A library list is defined by means of an S variable. The variable has the type string and the name begins with 'SYSPLAMALT-' (ALT stands for ALTernate library). The contents of the variable are set as follows:
SYSPLAMALT-<name> = '(<lib>,<lib>,...)'
<name>: | Rest of the variable name |
<lib>: | Library specification |
If the name of the library list is specified as a file name ":catid:$userid.SYSPLAMALT-", catalog ID and user ID are ignored. Names beginning with 'SYS' are reserved for future development. Lowercase letters in the contents of the "SYSPLAMALT-" variable are interpreted as uppercase letters.
Library lists have one level, which means that specifications in the library list are always interpreted as PLAM libraries or type redirections. All libraries in the list must be present.
Note
Library lists can only be accessed in read mode, i.e. if the LIBRARY operand specifies an output library, no library list is permitted. Wildcards are not allowed in library lists.
Example
Library lists allow convenient use of the make functionality for projects in which sources are administered with the borrowing mechanism. The sources are located in one of the libraries LIB.LOCAL or $GLOBAL.LIB. The borrowing mechanism is used to copy to and fro between these two libraries. In the make file, SYSPLAMALT-HUGO is specified directly as the only source library. The contents of SYSPLAMALT-HUGO determine which libraries are to be searched.
The contents of the libraries are as follows:
To combine the libraries LIB.LOCAL and $GLOBAL.LIB for the local make run:
/set-variable sysplamalt-hugo = '(lib.local,$global.lib)'
A.C from LIB.LOCAL, and B.C from $GLOBAL.LIB are searched.
With a central make run, SYSPLAMALT-HUGO only receives one library:
/set-variable sysplamalt-hugo = '($global.lib)'
Only sources A.C and B.C from $GLOBAL.LIB which have already been returned are searched. The statements for make are the same in both cases:
//modify-make-defaults library=sysplamalt-hugo
Validity of global and local libraries
A global library remains valid for the entire LMS run until either a new global library is opened or the library is closed by an explicit CLOSE-LIBRARY statement.
If a local library is also opened, then this is only valid within this one statement. On termination of this statement, the global library is valid once again.
The LMS statement SHOW-LIBRARY-STATUS (see "SHOW-LIBRARY-STATUS") provides information on the status of the libraries.
Working with more than one library
Only one global library can be assigned at a time. It if necessary to work simultaneously with two libraries, the second library must be locally defined.
If more than one library is assigned globally in the LMS run (by several OPEN-LIBRARY statements), LMS uses the most recently specified library.
Example
Member xyz, which is contained in library lib1, is copied to the library lib2 which already exists. lib1 is to be used as the global library and lib2 as the local library. Since the member type is not yet defined after calling LMS, it is defined as global member type S. The member is not to be renamed:
/START-LMS |
Redirection mechanism
In addition to the standard member types, LMS allows users to work with member types which they have defined themselves. These user-defined types should be derived from a standard type and have one or more apt names
(e.g. COBSRC, ASSSRC, etc.) defined as a synonym for the single-character designation of the standard type.
Programs which have not been prepared for user-defined types can nonetheless function with these members. PLAM offers a redirection mechanism that makes it possible to access libraries containing user-defined member types. All commands and programs in BS2000/OSD can use type redirection.
The redirection mechanism is implemented by means of the S variable SYSPLAMLIB, which is a structure-type variable. Its structure members specify what things are to be redirected and the destinations to which they are to be redirected.
The name of the structure member specifies what is to be redirected,
while the content of the structure member specifies the destination of the redirection.
The name of the structure member is composed of the link name and the user-defined member type.
The contents of the structure member consist of:
the library name and the member type or
the link name and the member type.
If no member type is specified, the member type indicated by the name of the structure member is used.
The S variable SYSPLAMLIB, which is written in the form of a variable assignment, has the following structure:
SYSPLAMLIB.<link>.<utype>= ́<libname>(TYPE=<typename> / *SAME) ́
or
SYSPLAMLIB.<link>.<utype>= ́*LINK(LINK=<linkname>,TYPE=<typename> / *SAME) ́
| Link name in the form <structured-name1..8> User-defined member type in the form <alphanum-name1..8> |
| Member type in the form <alphanum-name1..8> |
| Library name Link name in the form <structured-name1..8> The member type of the structure member contents is the same as the |
The content of the S variable is a string containing a library component and a type component which mirrors the real library environment. TYPE=*SAME in the variable content means <utype>. The library component must not be a library list.
Access via the S variable SYSPLAMLIB can be effected in two ways:
specification of a library via the file name SYSPLAMLIB.<link>
specification via the link name <link>
If SYSPLAMLIB is declared as a variable with SCOPE=VISIBLE or =TASK, the contents of the structure member are evaluated and redirected into the relevant library.
Example
The object of this example is to compile COBOL sources of the member type COBSRC. They are located in the library MY.COBLIB, which is specified by the link name SRCLIB. The copy members should be of the COBCOPY type and also located in the MY.COBLIB library.
/DECLARE-VARIABLE SYSPLAMLIB(TYPE=*STRUCTURE),SCOPE=*TASK ------------------------ (1) /SET-VARIABLE SYSPLAMLIB.SRCLIB.S = ́MY.COBLIB(COBSRC) ́ -------------------------- (2) /SET-VARIABLE SYSPLAMLIB.COBLIB.S = ́MY.COBLIB(COBCOPY) ́ ------------------------- (3) /ADD-FILE-LINK FILE-NAME=SYSPLAMLIB.SRCLIB,LINK=SRCLIB --------------------------- (4) /ADD-FILE-LINK FILE-NAME=SYSPLAMLIB.COBLIB,LINK=COBLIB /MODIFY-JOB-SWITCHES ON=1 /ASSIGN-SYSDTA *SYSCMD /ASSIGN-SYSLST #L /START-EXECUTABLE-PROGRAM COBOL85 COMOPT SOURCE-ELEMENT=LMSCOBS COMOPT SOURCE-VERSION=399 COMOPT MODULE=MY.COBLIB COMOPT SYSLST=(DIAG,MAP,SOURCE) END /STEP /MODIFY-JOB-SWITCHES OFF=1 /EXIT-PROC
(1) | Declares the central S variables (with SCOPE=TASK). |
(2) | Sets the redirection; redirection is effected via the link name SRCLIB or the file name SYSPLAMLIB.SRCLIB. For example, when the Cobol compiler accesses the type S, the access is mapped PLAM-internally to the type COBSRC. |
(3) | The copy members are mapped on the COBCOPY type as described at (2). |
(4) | Couples the link name SRCLIB with the real library SYSPLAMLIB.SRCLIB. This is necessary in the event that programs run a distributed check for the existence of the library. |
After SYSPLAMLIB.SRCLIB.S = ́MY.COBLIB(COBSRC) ́ the following situation exists:
Only COBSRC-type members can be accessed, and not all of those present in the library can be accessed. The members are accessed via member type S, and type S is shown instead of the “real” type COBSRC in program outputs.
The library MYCOPY contains members with the member type COBCOPY, which are to be designated with the member type S in an LMS run. To circumvent LMS checks, the library SYSPLAMLIB.COBLIB must exist.
/DECLARE-VARIABLE SYSPLAMLIB(TYPE=STRUCTURE) /SET-VARIABLE SYSPLAMLIB.COBLIB.S = ́MYCOPY(COBCOPY) ́ /ADD-FILE-LINK SYSPLAMLIB.COBLIB,LINK=COBLIB /START-LMS //SHOW-ELEM-ATTR *LIB(SYSPLAMLIB.COBLIB) Displays all members of the type COBCOPY from MYCOPY. Type S is logged. //SHOW-ELEM-ATTR *LIB(SYSPLAMLIB.COBLIB,*ALL(*ALL),COBCOPY) No hits (the type COBCOPY does not exist in the user view). //SHOW-ELEM-ATTR *LIB(SYSPLAMLIB.COBLIB,*ALL(*ALL),S) Displays all members of the type COBCOPY from MYCOPY. //SHOW-ELEM-ATTR (*LINK(COBLIB)) Displays all members of the type COBCOPY from MYCOPY. Type S is logged. //END