This section contains information necessary to communicate with the BS2000 Operating System services provided by the Entire Systems Management Adapter. The examples consist of Natural programs that reference Entire Systems Management Adapter views, and show the resulting output.
An example program for every available view is contained in an online tutorial delivered with Natural on Linux x64 (see Section Online Tutorial for more information).
This document covers the following topics:
Entire Systems Management Adapter views can be accessed from any
Natural program using the Natural statement PROCESS or FIND. Which
statement you will use depends on the type of view accessed, the access mode
required, and the number of records selected.
The PROCESS statement is intended for use only for
views related to performing an activity.
The FIND statement can be used to retrieve
information, which may consist of a set of records.
The PROCESS statement is used to request a function
(for example, allocate, update, or delete system data, issue operator
commands,) using the appropriate operating system service.
PROCESS view-name USING field-name=value
GIVING field-name
PROCESS FILE-ALLOCATE USING
DSNAME = 'USER.123',
NODE = 151
GIVING ERROR-CODE
Using the view FILE-ALLOCATE, a file named
USER.123 is allocated on the machine identified by the Entire
Systems Management Adapter node ID 151, and a code is returned.
The FIND statement can be used to display data from
views that require specification of fields. Selectable fields are indicated in
the view descriptions by a D in the Descriptor column
(see View
Descriptions).
FIND ... view-name WITH ... search criteria
Data is selected based on the specified search criteria (see next subsection).
FIND ACTIVE-JOBS WITH NODE = 151
AND JOB-NAME = ‘SM2*’
....
END-FIND
Using the ACTIVE-JOBS view, all jobs named
SM2 on the machine identified by the Entire Systems Management
Adapter node ID 151 are selected for display.
When FIND is used to access the Entire Systems
Management Adapter, search criteria can be used to specify values for
alphanumeric fields. Two search criteria are available:
* Acts as placeholder for one or more characters in the position;
_ Acts as placeholder for one character.
The following examples demonstrate the use of these search criteria:
FIND VTOC WITH VOLSER = 'V3380A' AND DSNAME = 'L99*LOAD*'
All files on volume V3380A whose names start with L99 followed
by anything, followed by LOAD, followed by anything, are selected;
for example:
L99COM.LOAD.NPR
L99.SAG.LOAD.DOCS
L99NPROC.LOAD
FIND VTOC WITH VOLSER = 'V3380A' AND DSNAME = '*SOURCE'
All files on volume V3380A whose names end with
SOURCE are selected; for example:
A1234.SOURCE
SAG.PP.SOURCE
AB.MYSOURCE
FIND ACTIVE-JOBS WITH JOB-NAME = 'L_ _AB*'
All jobs whose first characters are L, followed by
any 2 characters, followed by AB, followed by anything are
selected; for example:
L12ABJOB
LAAABX
LXXAB2YC
FIND NATPROC-USERS WITH USER-ID = '_ _ _ _ _'
All users of the Entire Systems Management Adapter whose identifiers contain exactly 5 characters are selected.
The FIND statement does not create an ISN list as
in the case of Adabas. Therefore, all functions related to ISN lists are not
supported; for example, RETAIN,
*NUMBER.
As Entire Systems Management Adapter does not support ISN lists
as it is done in Adabas, the meaning of the field
*NUMBER is different.
There are in general 3 possibilites:
*NUMBER = 0 means for Natural: fall in NO
RECORDS FOUND clause and Entire Systems Management Adapter did not find
any record which fulfilled the search criteria.
*NUMBER = 1 means for Natural one record found.
It will be returned for views with one wanted action such as
FILE-ATTRIBUTES, CATALOG-UPDATE.
*NUMBER = large
value: there are different large values for different
views such as CATALOG and READ-FILE.
Most of the views provided by ESA obtain data from the Operating System and return these data to the Natural program. Those views belong to the group of retrieval views. Another group of views allows you to modify Operating System objects in a certain way. These views belong to the group of update views.
All multi-record views with an Adabas file number greater than or
equal to 200 belong to update views. These views require a special programming
technique. A number of other update views support a single record request only
(for example, CATALOG-UPDATE, VTOC-UPDATE) and do not
need special programming considerations.
The field FUNCTION is provided in all update views.
It should contain blanks while creating the object, and the value
CLOSE if the object has been properly created. If no
CLOSE has been requested, the object is still in open state and
not completely built.
We recommend using the Natural statement PROCESS to
request update view services.
PROCESS update_view USING
NODE = #NODE
, FUNCTION = #FUNCTION
...
If more than one PROCESS statement is implemented in
a Natural program and the requests are related to one session only, for
example, to create a single file, the PROCESS statements must be
indicated as belonging together.
A typical example is the PROCESS WRITE-FILE USING
FUNCTION=' ' in one subroutine to create several records and
PROCESS WRITE-FILE USING FUNCTION='CLOSE' in a different
subroutine. The field IDENTIFIER must be used and filled with the
same 8-byte character string to indicate a session dealing with the same file
in different locations of a Natural program.
Another issue is implementing nested loops requesting update view
services. A separate IDENTIFIER must be used in every loop level
to make the calls linked to several sessions if for example
WRITE-FILE is used in different loop levels. If no
IDENTIFIER is provided, unpredictable results might occur in
nested loops.
If records have to be written to a file, the view
WRITE-FILE must be used to do it. The field RECORD is
defined as an alphanumeric field with a maximum length of 253 bytes only. Files
probably contain records larger than 253 bytes. Therefore, the pieces of such
records have to be delivered in segments.
Setting fields SEGMENT-NUMBER and
SEGMENT-LENGTH allows you to create records longer than 253 bytes.
Assuming a record length of 500 bytes, two view calls are needed.
SEGMENT-NUMBER=1, SEGMENT-LENGTH=250,
RECORD bytes 1-250 filled with data, create the first part of the
record, SEGMENT-NUMBER=2, SEGMENT-LENGTH=250,
RECORD bytes 1-250 the second part of the record.
Smaller segments could also be used (for example, 5 segments each 100 bytes long) but this would increase the number of calls and reduce the performance.
The following sample program reads an LMS element on one node and
copies the data to another LMS element on another node. It deals with segments
returned by the view READ-FILE. If an error occurs, the copying is
stopped immediately.
DEFINE DATA LOCAL
1 READ-FILE VIEW OF READ-FILE
2 ERROR-CODE
2 ERROR-TEXT
2 SYSTEM-CODE
2 SYSTEM-MESSAGE-CODE
2 DSNAME
2 ELEMENT
2 ELEMENT-TYPE
2 ELEMENT-VERSION
2 RECORD
2 RECORD-LENGTH
2 RECORD-NUMBER
2 SEGMENT-LENGTH
2 SEGMENT-NUMBER
2 END-OF-FILE
2 PRODUCT
2 KEY
1 WRITE-FILE VIEW OF WRITE-FILE
2 ERROR-CODE
2 ERROR-TEXT
2 SYSTEM-CODE
2 SYSTEM-MESSAGE-CODE
2 DSNAME
2 ELEMENT
2 ELEMENT-TYPE
2 ELEMENT-VERSION
2 RECORD
2 RECORD-LENGTH
2 RECORD-NUMBER
2 SEGMENT-LENGTH
2 SEGMENT-NUMBER
2 PRODUCT
2 DISP
2 KEY
2 FUNCTION
*
1 #I-DSNAME (A54) INIT <'$NPR.NPRvrs.DEV'>
1 #I-ELEMENT (A64) INIT <'XCOMMAIN'>
1 #I-ELEMENT-TYPE (A8) INIT <'P'>
1 #I-NODE (N3) INIT <113>
1 #I-PRODUCT (A1) INIT <'M'>
*
1 #O-DISP (A3) INIT <'NEW'>
1 #O-DSNAME (A54) INIT <'$PRD.NPRvrs.DEV'>
1 #O-FUNCTION (A8) INIT <' '>
1 #O-ELEMENT (A64) INIT <'XCOMMAIN'>
1 #O-NODE (N3) INIT <114>
1 #O-PRODUCT (A1) INIT <'M'>
*
1 #CLOSE-NEEDED (L) INIT <FALSE>
*
END-DEFINE
*
* Main loop reading the segments of the input file to
* write the data to output on the target node.
*
FIND READ-FILE WITH NODE = #I-NODE
AND DSNAME = #I-DSNAME
AND ELEMENT = #I-ELEMENT
AND ELEMENT-TYPE = #I-ELEMENT-TYPE
AND PRODUCT = #I-PRODUCT
*
IF READ-FILE.ERROR-CODE NE 0
WRITE READ-FILE.ERROR-CODE
READ-FILE.ERROR-TEXT
READ-FILE.SYSTEM-CODE
READ-FILE.SYSTEM-MESSAGE-CODE
IF #CLOSE-NEEDED EQ FALSE
ESCAPE ROUTINE
END-IF
END-IF
*
IF READ-FILE.END-OF-FILE EQ 'YES' OR
READ-FILE.ERROR-CODE NE 0
ASSIGN #O-FUNCTION = 'CLOSE'
END-IF
*
PROCESS WRITE-FILE USING
NODE = #O-NODE
, DSNAME = #O-DSNAME
, DISP = #O-DISP
, FUNCTION = #O-FUNCTION
, PRODUCT = #O-PRODUCT
, ELEMENT = #O-ELEMENT
, ELEMENT-TYPE = READ-FILE.ELEMENT-TYPE
, ELEMENT-VERSION = READ-FILE.ELEMENT-VERSION
, RECORD = READ-FILE.RECORD
, RECORD-LENGTH = READ-FILE.RECORD-LENGTH
, RECORD-NUMBER = READ-FILE.RECORD-NUMBER
, SEGMENT-LENGTH = READ-FILE.SEGMENT-LENGTH
, SEGMENT-NUMBER = READ-FILE.SEGMENT-NUMBER
, KEY = READ-FILE.KEY
*
IF WRITE-FILE.ERROR-CODE NE 0
WRITE WRITE-FILE.ERROR-CODE
WRITE-FILE.ERROR-TEXT
WRITE-FILE.SYSTEM-CODE
WRITE-FILE.SYSTEM-MESSAGE-CODE
ESCAPE ROUTINE
END-IF
*
IF READ-FILE.ERROR-CODE NE 0
ESCAPE ROUTINE
END-IF
*
ASSIGN #CLOSE-NEEDED = TRUE
*
END-FIND
*
END
Example programs can be found in the Entire Systems Management Adapter online tutorial. A full list of field names for the various Operating Systems is contained in the view descriptions; see View Descriptions.
Note:
Programs whose names start with B are taken from a
BS2000 environment.