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.