This document covers the following topics:
The principle of operation behind the Entire System Server is surprisingly simple.
Just as a Natural program would access conventional data, Entire System Server views can be called from a Natural program using the Natural statements Process or Find, depending on the view involved. Just as a database identifier is required for a standard call to a database, the call to the Entire System Server is identified by a node number.
The Entire System Server recognizes the node number and processes the call, returning the requested operating system service or information to the program. Each operating system in the computer network is identified by the node number, thus enabling access to any system from anywhere within the network.
This section illustrates the use of the Entire System Server with some example program coding. The examples illustrate how simple, easy-to-write Natural programs can be used to display system information on the terminal screen, requiring only a minimum of input from the user. However, this is not the only use of the Entire System Server.
The examples should be seen as a starting point for more powerful applications that can process system information automatically, invisible to the user.
In z/OS systems, the IEBCOPY utility can be invoked using only a few lines
of code in a Natural program:
*
* The INPUT statement is a standard Natural statement which
* defines a map that is displayed on the terminal screen when the
* program is run. The map prompts the user to specify the source
* member to be copied and the destination member:
*
INPUT // ' Input Dsname ...:' IEBCOPY.IN-DSNAME
/ ' Volser .........:' IEBCOPY.IN-VOLSER
// ' Output Dsname ..:' IEBCOPY.OUT-DSNAME
/ ' Volser .........:' IEBCOPY.OUT-VOLSER
// ' Member .........:' IEBCOPY.IN-MEMBER
/ ' New Name .......:' IEBCOPY.OUT-MEMBER
// ' Replace ........:' IEBCOPY.REPLACE '(yes/no)'
....
*
* The PROCESS statement calls the IEBCOPY utility via the
* Entire System Server view IEBCOPY to perform the copy
* operation.
* The NODE variable is used if the destination member resides on
* a different node:
*
....
PROCESS IEBCOPY USING IN-DSNAME = IEBCOPY.IN-DSNAME
, OUT-DSNAME = IEBCOPY.OUT-DSNAME
, IN-MEMBER = IEBCOPY.IN-MEMBER
, OUT-MEMBER = IEBCOPY.OUT-MEMBER
, REPLACE = IEBCOPY.REPLACE
, NODE = ##NODE
....
* In case of an error, the user can be reprompted with the input
* map and an error message:
....
IF ERROR-CODE > 0
REINPUT ERROR-TEXT
END-IF
Running such a simple Natural program results in the following online prompt:
IEBCOPY utility
Input Dsname ...: ______________________________________________________
Volser .........: ______
Output Dsname ..: ______________________________________________________
Volser .........: ______
Member .........: __________
New Name .......: __________
Replace ........: ___ (yes/no)
|
All the user has to do is fill in the required information and press Enter to perform the copy operation for example:
IEBCOPY utility
Input Dsname ...: MY.OLD.DATASET________________________________________
Volser .........: ______
Output Dsname ..: MY.NEW.DATASET_________________________________________
Volser .........: ______
Member .........: OLDNAME____
New Name .......: NEWNAME____
Replace ........: ___ (yes/no)
|
By running such a simple Natural program, operating system utilities can be used without any special knowledge of utility-specific syntax on the part of the user.
The following example program allows the user to perform certain disk maintenance functions:
....
* When this program is run, the user is presented with the map
* defined by the following INPUT statement. Possible functions to * maintain a
* catalog entry are: RENAME, SCRATCH, PURGE:
*
INPUT // ' Function ..:' VTOC-UPDATE.FUNCTION
// ' Volume ....:' VTOC-UPDATE.VOLSER
/ ' Dsname ....:' VTOC-UPDATE.DSNAME
// ' New Name ..:' VTOC-UPDATE.NEWNAME
....
*
* The disc is accessed by addressing the corresponding fields on * the view
VTOC-UPDATE using the PROCESS statement. Within a
* multi-CPU environment, the NODE variable allows the program to * access the
disc on another computer:
*
PROCESS VTOC-UPDATE USING NODE = ##NODE
, DSNAME = VTOC-UPDATE.DSNAME
, VOLSER = VTOC-UPDATE.VOLSER
, FUNCTION = VTOC-UPDATE.FUNCTION
, NEWNAME = VTOC-UPDATE.NEWNAME
Again, this example shows that no special knowledge of operating system structures is required to write and use such a program; indeed, the same program can be used in different operating systems.
The following example shows how a Natural program can retrieve storage unit information and display it to the user:
...
*
* The FIND statement addresses the view UNIT-ATTRIBUTES to read
* the desired device. The NODE parameter is used when reading the
* information from a different machine within the computer
* network:
*
FIND UNIT-ATTRIBUTES WITH CLASS = 'DASD'
AND NODE = ##NODE
....
*
* Using the DISPLAY statement, the output is presented to the
* user when the program is run:
*
DISPLAY (ZP=OFF)
'Unit/Adr' UNIT-ATTRIBUTES.UNIT
'Unit/Type' SERIES
'avail./Unit' DEVICE-STATUS
'OPEN/DCB''S' DCB-COUNT
5X
'mounted/Volume' VOLSER
'mount/Attributes' MOUNT-STATUS
'avail./of Volume' VOLUME-STATUS
'FREE/CYL' FREE-CYLINDERS
'FREE/TRACKS' FREE-TRACKS
'FREE/EXTENTS' FREE-EXTENTS
ADD 1 TO #NUMBER
END-FIND
...
Running the program with the above code produces output similar to the following:
Unit Unit avail. OPEN mounted mount avail. FREE FREE FREE Adr Type Unit DCB'S Volume Attributes of Volume CYL TRACKS EXTENTS ---- ------ ------- ----- ------- ---------- --------- ----- ------ ------- 300 3380 ONLINE 102 SYSF06 RESIDENT PRIVATE 367 50 20 310 3380 ONLINE 9 NAT002 RESIDENT PRIVATE 70 138 48 320 3380 ONLINE 5 NDM001 RESIDENT PRIVATE 96 13 16 330 3380 ONLINE 65 XKGSD1 RESIDENT PRIVATE 293 280 58 350 3380 ONLINE 21 USR8A6 RESIDENT STORAGE 140 1080 236 360 3380 ONLINE 7 DCN002 RESIDENT PRIVATE 131 19 370 3380 ONLINE 55 DBDC06 RESIDENT PRIVATE 1018 63 19 380 3380 ONLINE 6 EUP003 RESIDENT PRIVATE 29 141 23
The file maintenance group of views allow users to allocate files, display file information, and rename, delete or copy files using small Natural programs.
The following example prompts the user for the name of a dataset to be compressed.
....
*
* The prompt is defined using the INPUT statement, allowing the
* user to specify the dataset to be compressed:
*
INPUT // ' Dataset ...:' FILE-MAINTENANCE.DSNAME
/ ' Volume ....:' FILE-MAINTENANCE.VOLSER
*
* Compression is performed by addressing the FILE-MAINTENANCE
* view using the PROCESS statement.
* The NODE parameter must be used
* when compressing a dataset that resides on a different node within
* the computer network:
*
PROCESS FILE-MAINTENANCE USING FUNCTION='COMPRESS'
, DSNAME = FILE-MAINTENANCE.DSNAME
, VOLSER = FILE-MAINTENANCE.VOLSER
, NODE = ##NODE
....
Libraries can thus be maintained easily using only a few lines of Natural code.
The following example shows how a simple Natural program can perform a file transfer operation from one z/OS system to another in a network. Note that in this example, up to three Entire System Server nodes are involved: the program runs on one machine, but can copy a file residing on a second machine to a third machine within the computer network.
*
* The INPUT statement defines an input mask to be displayed
* when the program is run, in which the user can specify the
* source and target datasets.
* The NODE parameter specifies the node, if
* different from the node on which the program runs.
*
INPUT // ' Dataset...:' COPY-FILE.FROM-DSNAME
/ ' Member....:' COPY-FILE.FROM-MEMBER
/ ' Volser....:' COPY-FILE.FROM-VOLSER
/ ' Node......:' COPY-FILE.FROM-NODE
// ' to' (I)
// ' Dataset...:' COPY-FILE.TO-DSNAME
/ ' Member....:' COPY-FILE.TO-MEMBER
/ ' Volser....:' COPY-FILE.TO-VOLSER
/ ' Node......:' COPY-FILE.TO-NODE
/ ' Replace...:' #REPLACE
*
* The copy operation is performed by the PROCESS call to the
* COPY-FILE view, specifying the source and target dataset
* characteristics:
*
PROCESS COPY-FILE USING FROM-DSNAME = COPY-FILE.FROM-DSNAME
, FROM-MEMBER = COPY-FILE.FROM-MEMBER
, FROM-VOLSER = COPY-FILE.FROM-VOLSER
, FROM-NODE = COPY-FILE.FROM-NODE
, TO-DSNAME = COPY-FILE.TO-DSNAME
, TO-MEMBER = COPY-FILE.TO-MEMBER
, TO-VOLSER = COPY-FILE.TO-VOLSER
, TO-NODE = COPY-FILE.TO-NODE
, NODE = ##NODE
, REPLACE = #REPLACE '(Yes/No)'
The Entire System Server provides a number of views that allow users to retrieve system information from a Natural program. Views are available for display of address space, main storage, as well as active tasks.
The following lines of Natural code call the ACTIVE-JOBS view and specify
the information items required for display. The NODE parameter is
used to access a different machine in the computer network.
FIND ACTIVE-JOBS WITH NODE = ##NODE
AND JOB-NAME = #JOB-NAME
AND TYPE = #TYPE
AND CPU-USED = #CPU-USED
AND STATUS = #STATUS
....
END-FIND
The resulting output from this program is presented in the following format in a z/OS system:
Job-Name Type Status Cpu used Region JobNr. ProcName StepName
*_______ *_____ *_______ __________ ______ ______ ________ ________
*MASTER* STC NON-SWAP 2226.21 268 3513
PCAUTH STC NON-SWAP 0.01 164 PCAUTH
TRACE STC NON-SWAP 0.01 104 TRACE
GRS STC NON-SWAP 0.03 1016 GRS
DUMPSRV STC NON-SWAP 2.66 92 DUMPSRV DUMPSRV
CONSOLE STC NON-SWAP 305.78 204 CONSOLE
ALLOCAS STC NON-SWAP 0.01 148 ALLOCAS
SMF STC NON-SWAP 6.57 152 IEFPROC SMF
LLA STC NON-SWAP 1.69 332 LLA LLA
ACF2 STC NON-SWAP 1.61 172 IEFPROC ACF2
JES2 STC NON-SWAP 1607.18 936 JES2 JES2
RMF STC NON-SWAP 10.72 76 3525 IEFPROC FRMF
TMON8DLS STC NON-SWAP 281.03 568 3202 TMON8DLS TMON8DLS
TMDBDLS STC NON-SWAP 33.66 248 3122 TMDBDLS TMDBDLS
TMONMVS STC NON-SWAP 79.22 152 4013 TMONMVS TMONMVS
Using view RECEIVE-EMAIL and the functions STATUS,
LIST, READ and DELETE under statement
FIND you can manage your incoming e-mails under z/OS. For communication the
Internet Message Access Protocol (IMAP) is used. IMAP is defined in RFC-3501. The name of
the mail server IMAP-HOST and the port number IMAP-PORT
for access are specified by startup parameters. Other startup
parameters specify the default number of mails to be listed by the LIST
function and the maximum amount of mails to be read in. This helps to prevent sending
unnecessary huge amounts of data for large mailboxes. See also LIST-NUM-MAILS and LIST-NUM-MAILS-MAX.
z/OS allows you to use Application Transparent Transport Layer Security (AT-TLS). This enables a secure access using port 993. Login credentials such as user ID and password are handed over in the Natural program.
We give some simple examples to explain the functions STATUS,
LIST, READ and DELETE. Upon this we discuss more
complex use cases:
Read all Mails from a Specific Sender with a Specific Search Term in the Subject Line
List the Latest 1000 Mails from a Mail Box Containing 10.000 Mails
The following example illustrates a use case for the function STATUS in
which we request
the total number of mails (NUMBER-MAILS);
the number of unread mails (NUMBER-NEW-MAILS).
FIND RECEIVE-EMAIL WITH NODE = #NODE
AND FUNCTION = 'STATUS'
AND USERID = 'horst.mustermann@softwareag.com'
AND PASSWORD = #PASSW
PRINT '=' NUMBER-MAILS
PRINT '=' NUMBER-NEW-MAILS
END-FIND
Note
It is useful to invoke this function from time to time to check if new mails have
arrived. If so, you might then want to invoke other functions to list, read or delete
mails.
Using function LIST you can display directory data of mails such as
STATUS, SENDER-MAIL, SENDER-NAME,
SUBJECT, RECIPIENTS, MESSAGE-ID,
UID or DATE. This is illustrated in the following
statement:
FIND RECEIVE-EMAIL WITH NODE = #NODE
AND FUNCTION = 'LIST'
AND USERID = 'horst.mustermann@softwareag.com'
AND PASSWORD = #PASSW
AND LIST-NUM-MAILS = 15
…
PRINT '=' STATUS
PRINT '=' SENDER-MAIL
PRINT '=' SENDER-NAME
PRINT '=' SUBJECT
PRINT '=' RECIPIENTS
PRINT '=' MESSAGE-ID
PRINT '=' UID
PRINT '=' DATE
END-FIND
Notes:
LIST-NUM-MAILS you can limit the number of mails to be
listed. If this field is omitted, a default defined in the startup parameters is
assumed.
STATUS two different values can be displayed:
NEW for a mail that yet has not been read and SEEN for a
mail that has already been read.
MESSAGE-ID is a unique world-wide reference. A
MESSAGE-ID is therefore long and complex. However, a
MESSAGE-ID cannot be used to read or delete a mail using IMAP. Instead,
IMAP uses the UID as identifier.
STATUS = 'NEW' to the FIND statement only new
mails will be listed.
SENDER-MAIL =
'richard.wagner@softwareag.com' to the FIND statement you can
limit the list to mails from a specific sender. You can also use a search term
embraced by stars (*) to limit your search to a sender that contains a
specific substring, for example to list mails from senders that contain the string
"richard" independent of its position specify
SENDER-MAIL='*Richard*' or SENDER-MAIL='*Wagner*'.
The next example illustrates the usage of function Read:
FIND RECEIVE-EMAIL WITH NODE = #NODE
AND FUNCTION = 'READ'
AND USERID = 'horst.mustermann@softwareag.com'
AND PASSWORD = #PASSW
AND UID = #UID
PRINT '=' RECORD
END-FIND
Notes:
UID (unique identifier).
UIDs are displayed using function LIST.RECORD.
You can delete a mail using a FIND statement similar to the following
example:
FIND RECEIVE-EMAIL WITH NODE = #NODE
AND FUNCTION = 'DELETE'
AND USERID = 'horst.mustermann@softwareag.com'
AND PASSWORD = #PASSW
AND UID = #UID
PRINT '=' ERROR-CODE
PRINT '=' ERROR-TEXT
PRINT '=' MAILSERVER-RESPONSE
END-FIND
If the call was successful, the following message is displayed:
ERROR-CODE: 0 ERROR-TEXT: ESY3000 MAILSERVER-RESPONSE: Delete successful
Assume we want to read all and only those mails with a matching term in the subject line from a specific sender:
FIND RECEIVE-EMAIL WITH NODE = #NODE
AND FUNCTION = 'LIST'
AND USERID = 'horst.mustermann@softwareag.com'
AND PASSWORD = #PASSW
AND SUBJECT = ‘*SALE*’
AND SENDER-MAIL = 'my.boss@company.com'
END-FIND
In this example we list mails from one sender that contain the word "SALE".
As already shown above, a term embraced by stars (*) matches any string in which
the term occurs independent of its position. In this example case we get all messages in
which the term SALE occurs somewhere in the subject line. For the sender,
on the other hand, we require an exact match, that is we restrict our statement to mails
with a sender that exactly matches the e-mail address of the boss.
Assume a mailbox contains approximately 10.000 mails. We want to list the latest 1000.
We could achieve this by one LIST call. However, this would imply an inadequately long
response time. To reduce response time, we successively call the LIST
command for a fraction (here 100) until the required amount of mails is listed. This is
done by the following loop:
#START-MAIL-NR := #NUMBER-OF-MAILS
#LIST-NUM := 100
FOR #I = 1 TO 10
FIND RECEIVE-EMAIL WITH NODE = #NODE
AND FUNCTION = 'LIST'
AND USERID = 'horst.mustermann@softwareag.com'
AND PASSWORD = #PASSW
AND LIST-NUM-MAILS = #LIST-NUM
AND LIST-NUM-MAILS-START = #START-MAIL-NR
END-FIND
#START-MAIL-NR := #START-MAIL-NR - #LIST-NUM
END-FOR
Before the loop is entered, variable START-MAIL-NR is set to
NUMBER-OF-MAILS. This ensures that the list starts with the latest
mail.
Note that for each iteration step the position from which to list mails, controlled by
variable START-MAIL-NR, has to be decremented by the number of mails listed
in one step (= LIST-NUM = 100).
After the first iteration step, the starting point is decremented by
LIST-NUM-MAILS (=100) to prepare the second iteration step,
and so on until the nth step.
This section covers access to the z/OS UNIX file system within NATURAL applications. NATURAL itself already provides this in TSO or batchjobs but not in online monitors like CICS or Com-plete. Now, Entire System Server itself provides an access to the z/OS UNIX file-system. There are 3 new views called WRITE-UNIX-FILE, READ-UNIX-FILE and UNIX-DIRECTORY. A fully qualified path-name must be provided to locate the file you want to read or write to. Here is an example of how to write to a UNIX:
#RECORD-LENGTH := 80 #PATH := '/u/nat/wkk/beispiele/lrec80 ' PROCESS WRITE-UNIX-FILE USING NODE = #NODE , PATH = #PATH , RECORD = #RECORD , RECORD-LENGTH = #RECORD-LENGTH
Note the fully qualified pathname for the file to be written to. It must start with a
slash. Also note that we have set RECORD-LENGTH to 80 characters. Otherwise,
a default record-length of 132 would be used. The maximum value for
RECORD-LENGTH is 253. At the end the file must be closed as in other
“update views” such as WRITE-FILE or SUBMIT:
PROCESS WRITE-UNIX-FILE USING NODE = #NODE , FUNCTION = 'CLOSE'
The DDM looks like this:
1 FN FUNCTION A 8
Function to be performed:
blank Write a record
CLOSE All records have been written, close file.
1 A1 PATH A 128
Fully qualified Path of file to be written, starting with /
1 A4 RECORD A 253
Record to be written.
1 ID IDENTIFIER A 8
Needed if multiple update views are executing in
parallel, all requests for the same file must have same Identifier.
1 A7 RECORD-LENGTH N 3.0
Length of record, default is 132.
How to z/OS UNIX file is demonstrated by the following example:
#PATH := '/u/nat/user/examples/lrec80 '
#RECORD-LENGTH := 80
FIND READ-UNIX-FILE WITH NODE = #NODE
AND PATH = #PATH
AND RECORD-LENGTH = #RECORD-LENGTH
Note that you only need to specify RECORD-LENGTH for files that contains a
record greater than 132 characters. Here, we want to read a file containing a record with
250 characters:
#PATH := '/u/nat/user/examples/lrec250'
#RECORD-LENGTH := 250
FIND READ-UNIX-FILE WITH NODE = #NODE
AND PATH = #PATH
AND RECORD-LENGTH = #RECORD-LENGTH
The DDM looks like this:
A1 PATH A 128
Path of file to be read.
A4 RECORD A 253
Record to be read.
A7 RECORD-LENGTH N 3.0 D
By specifying the path of a directory you can get a list of all files and (sub)directories of that directory including a list of entries such as user ID, access-rights and file size. Here is an example:
#PATH := '/u/nat/user/examples/ld'
FIND UNIX-DIR WITH NODE = #NODE
AND PATH = #PATH
The DDM looks like this:
DB Name F Leng
A1 PATH A 54
Path of directory to be read.
A2 FILE A 54
file name of directory
A3 TYPE A 1
D=Directory,3=standard file , see layout of BPXYFTYP
A4 ACCESS-USER A 3
Access rights of User, R=read, W=write, X=Execute.
A5 ACCESS-GROUP A 3
Access rights of group, R=read, W=write, X=Execute.
A6 ACCESS-OTHER A 3
Access rights for others, R=read, W=write, X=Execute.
A7 OWNER A 8
Owner of this file.
A8 OWNER-GROUP A 8
Group of owner.
A9 FILE-SIZE N 8.0
Size of file in bytes.
Field TYPE can be interpreted as defined in BPXYFTYP
** BPXYFTYP: File type definitions ** FT_DIR EQU 1 Directory File FT_CHARSPEC EQU 2 Character Special File FT_REGFILE EQU 3 Regular File FT_FIFO EQU 4 Named Pipe (FIFO) File FT_SYMLINK EQU 5 Symbolic link * EQU 6 Reserved for Block Special FT_SOCKET EQU 7 Socket File
The above examples illustrate the kind of tasks the Entire System Server can be used for, but they are not exhaustive. Small programs can be written for specific tasks, but more elaborate site-specific applications can be built to automize whole areas of data center tasks. As already mentioned, Software GmbH provides ready applications based on the Entire System Server in the area of operations scheduling, event management, and output handling (see the section What is Entire System Server?).
Additionally, the Entire System Server installation medium provides a comprehensive online tutorial consisting of sample programs for every Entire System Server view. These programs not only serve as a useful online training guide, but can also be customized to meet the requirements of the installation, and can be used as a starting point for the development of more complex applications.
Experienced application developers and system programmers will readily recognize the potential of using the Entire System Server as a powerful aid to build tools for their work. If we can say that the Entire System Server provides the brush and the colors, then the application developers and system programmers paint the picture. As with all creative artists, their ingenuity is the limit.