HP 3000 Manuals

Writing and Executing Script Files [ Using NS3000/XL Network Services ] MPE/iX 5.0 Documentation

Using NS3000/XL Network Services

Writing and Executing Script Files

A script file includes all commands, flow control statements, and data
that allow you to remotely access and perform operations on nodes. To
execute the script file, it must reside on the management node on which
NetCI is installed.

Creating a Script File

You can create a script file with any text editor while you are at the
MPE colon prompt or from within NetCI. If you are in NetCI, you need to
run the editor program from the management node. For example, you enter

NetCI>K RUN TDP.PUB.SYS

to run the editor on node K which is the management node.

Make sure the editor program resides on the management node, and the user
associated with the session is allowed access to the editor. The script
file you created will then reside on the management node in the session's
user account/group that was specified in NetCI configuration. In this
example, the new script file will reside on management node K in the
operator.sys account.

Special Symbols

When you create a script file, remember the following:

* Use the symbol % (percentage sign) preceding an MPE or NetCI
command. Subsystem command and program input records should not be
preceded by %.

* Use the symbol ! (exclamation mark) and a parms position number
within the script file to indicate the value or string (which is
specified with the PLAY command) to be used.

In the PLAY command, the first parameter specified after the file name
is considered as position 1. If you specify !1 within your script file,
NetCI will substitute the first parms value or string for !1. The file
name is considered as position 0.

Reserved Characters

There are also reserved characters that you can use in the script file.
Whenever the reserved character is encountered, NetCI substitutes it with
specific data as shown in Table 7-1. NetCI does not refer to the PLAY
command for a parms value or string. For example, when the script file
contains !a, NetCI substitutes the current account name for !a.

Special Slash Character

When a script file is executed on a node or list, the MPE mode is in
effect. For example, when you enter

NetCI>Y PLAY SCRIPT1

Table 7-1. Reserved Characters

---------------------------------------------------------------------------------------------
| | |
| Reserved Characters | Substituted String |
| | |
| |
| | |
| !u | Current user name |
| | |
| |
| | |
| !g | Current group name |
| | |
| |
| | |
| !a | Current account name |
| | |
| |
| | |
| !h | Home node |
| | |
| |
| | |
| !n | Current or default node on which execution |
| | is occurring |
| | |
| |
| | |
| !! | Indicates an exclamation mark and not a |
| | substitution for a parms value or string |
| | |
---------------------------------------------------------------------------------------------

you are in MPE mode. MPE assumes only MPE commands are executed in MPE
mode. If the script file contains NetCI commands, you must precede these
commands with a special slash (/) character in order for the commands to
be interpreted as NetCI commands. Refer to SCRIPT1 in the following
example on the use of the slash character.

Comment Command

A NetCI COMMENT command is available to allow you to include comments in
a script file (containing NetCI commands) that will execute in NetCI
mode. Refer to Example 1 for using the NetCI COMMENT command. Since
there is an MPE COMMENT command, you can also use this command in a
script file (containing MPE commands) that will execute on a node or
list. When a script file executes on a node/list, you will be in MPE
mode. Refer to Example 2 for using the MPE COMMENT command in a script
file executing in MPE mode.

Example 1

This example executes a script file called SCRIPT1 containing NetCI
commands. To execute the script file, you enter

NetCI>PLAY SCRIPT1

Since you are executing SCRIPT1 in the NetCI mode, you are using the
NetCI COMMENT in the script file. The SCRIPT1 script file contains the
following commands:

%comment show NetCI nodes' adds comment that this file will list the
%comment and lists' configu- NetCI configuration for the NET3 network.
%comment ration

%log logfile1 redirects output to log file called
LOGFILE1. A slash does not need to
precede the NetCI command since you will
be in a NetCI mode. Refer to the LOG
command discussed later in this section.

%shownode @ displays the NetCI configuration for all
nodes.

%showlist @ displays all the lists and the nodes on
each list.

%logreset resets output back to the screen. Refer
to the LOGRESET command discussed later
in this section.

Example 2

This example executes a script file called SCRIPT2 on node Y, causing you
to be in MPE mode. Since there is also an MPE COMMENT command, you do
not need to use the NetCI COMMENT command. To execute the script file,
you enter

NetCI>Y PLAY SCRIPT2 FINANCE

The SCRIPT2 script file contains the following commands:

%comment run listdir5 adds comment that this file runs the
%comment program listdir5 program.

%/log logfile2 redirects output to a log file called
LOGFILE2. A slash must precede the NetCI
LOG command since you will be in MPE mode.
Refer to the LOG command discussed later in
this section.

%run listdir5.pub.sys executes program.

listacct !1 lists attributes for the first parms value
(which is FINANCE) specified in PLAY
command. This is a subsystem command within
the program calledlistdir5.

listgroup @.!1 lists attributes for all groups in FINANCE.
This is a subsystem command within listdir5.

listuser @.!1 lists attributes for all users in FINANCE.
This is a subsystem command within listdir5.

exit exits program. This is a subsystem command
to exit the listdir5 program.

%/logreset resets output back to the screen. Refer to
the LOGRESET command discussed later in this
section.

SCRIPT2 runs a program that lists attributes according to groups and
users for an account called FINANCE. We know this information is for the
FINANCE account because !1 references the first parms value specified in
PLAY. The output will be stored in the log file called LOGFILE2.

Example

This example shows how the slash must precede the NetCI LOG, LOGRESET,
LET, WHILE, INC, and ENDWHILE commands since the MPE mode will be
established when you execute the script file on a node or list. For
example, when you enter

NetCI>I PLAY SCRIPT3

you will be in MPE mode. A slash must precede each NetCI command as
shown in 1SCRIPT3. The SCRIPT3 script file contains the following:

%/LOG LOGFILE2
%/LET V=1
%/WHILE V 2
%SHOWJOB
%/INC V
%/ENDWHILE
%/LOGRESET

Special Considerations

There are several considerations that apply to scripting which must be
considered since input is redirected from the script file instead of the
terminal. These considerations are:

* Include a password with the logon information during configuration.
If you do not include a password, NetCI will automatically assign a
password to prevent the system from prompting you for a password.

* Include the termtype option with the logon information during
configuration to prevent a remote application from polling the
terminal for termtype during connection establishment. This will
occur if the application was part of a logon UDC (such as setting
function keys). If you do not include the termtype option, and the
remote application requires it, the remote node connection will hang.

Flow Control Statements

Flow control statements may be used in script files to control execution
of NetCI commands. Refer to the following pages for more details of the
flow control statements.

IF Statement

The IF statement controls the execution of a block of commands or a
single command depending on whether the expression (or condition) is
true.

The IF statement consists of the reserved word IF, an expression
(condition), commands, the reserved word ELSE and other commands which
are optional, and the reserved word ENDIF.

When NetCI executes an IF statement, the following occurs:

1. NetCI evaluates the expression which is the condition.

2. If the condition is true and ELSE is specified, it executes the
subsequent commands that follow the condition and skips the
commands after ELSE to statements or commands after ENDIF. If the
condition is true and ELSE is not specified, it executes the
subsequent commands that follow the condition.

3. If the condition is false and ELSE is specified, it executes the
commands after ELSE. If the condition is false and ELSE is not
specified, flow control skips to statements or commands after
ENDIF.

Parameters

expression

Specifies the condition that determines whether the commands following it
will execute. The expression must be in the following format:

identifier operator identifier

The identifier is a variable name, numerical value, or known variable
(set flag) in NetCI. The operator is an equal sign (=), not equal sign
(<>), greater than sign (>), or less than (<) sign.

commands

Specifies the commands to be executed provided the expression (condition)
is true.

commands

Specifies the commands following ELSE to be executed provided the
expression (condition) is not true. The ELSE statement and commands are
optional.

Discussion

You may nest both IF and WHILE statements in script files. A maximum of
20 IF statements and 20 WHILE statements (for a total of 40 statements)
may be nested together within the same script file.

INC Statement

The INC statement increases the value of a variable by one.

Syntax
_____________________________________
| |
| INC variable |
_____________________________________

Parameters

variable

Specifies the variable to which the value is assigned. This variable
must begin with an alpha character.

Discussion

If the value of the variable is 32,767, an error message will display.

Example

%/LOG LOGFILE2
%/LET V=1
%/WHILE V <2
%SHOWJOB
%/INC V
%/ENDWHILE
%/LOGRESET

LET Statement

The LET statement assigns a value to a variable, or a variable to a
variable.

The LET statement consists of the equal sign which is an assignment
operator. It does not indicate equality but is a signal that the value
or variable on the right of the equal sign be assigned to the variable on
the left.

Syntax
_____________________________________
| |
| LET variable = value |
_____________________________________

Parameters

variable

Specifies the variable to which the value is assigned. The variable must
begin with an alpha character and cannot be numeric, greater than 15
characters, or a node or list name.

value

Specifies a constant between -32,768 and 32,767 or a variable identifier.

Discussion

This statement can be entered interactively or specified in a script
file.

WAIT Statement

The WAIT statement returns control to the next command after waiting the
specified number of seconds.

Syntax
_____________________________________
| |
| WAIT seconds |
_____________________________________

Parameter

seconds

Specifies the number of seconds before the next command is executed. The
number must be a positive integer not greater than 32,767.

Discussion

If you want to wait longer than the maximum number of seconds allowed,
specify the WAIT statement as many times as needed.

WHILE Statement

The WHILE statement executes commands repeatedly as long as a given
expression is true.

The WHILE statement consists of the reserved word WHILE, an expression
(condition), commands, and the reserved word ENDWHILE.

When NetCI executes a WHILE statement, the following occurs:

1. NetCI evaluates the expression which is the condition.

2. If the condition is true, it executes the subsequent commands in
the script file until ENDWHILE is encountered, and then
re-evaluates the condition. When the condition becomes false,
execution resumes at the next statement or command after ENDWHILE.

3. If the condition is false, the subsequent commands following this
condition will not execute, and flow control skips to statements
or commands after ENDWHILE.

Parameters

expression

Specifies the condition that determines whether the commands following it
will execute. The expression must be in the following format:

identifier operator identifier

The identifier is a variable name, numerical value, or known variable
(set flag) in NetCI. The operator is an equal sign (=), not equal sign
(<>), greater than sign (>), or less than (<) sign.

commands

Specifies the commands to be executed provided the expression (condition)
is true.

Discussion

The INC statement may be used with the WHILE statement to increase the
value of the expression specified with WHILE. Refer to the INC statement
which was previously discussed in this section.

Logging (Redirecting Output)

Logging allows you to store in a log file all output from a process or
operation that takes place on configured nodes. You can redirect output
to a log file with the LOG command and direct output solely to the screen
with the LOGRESET command. These two commands may be used either inside
or outside a script file. Refer to the pages that follow for more
information on these two commands. When you are in logging only mode,
output will be directed to the log file and to the screen. This
capability enables you to respond with input from the keyboard since the
scripting mode is not activated.

Accessing Log File

The log file containing the output will reside on the management node
(where NetCI is installed) in the user.account configured for this node.
For example, when you enter

NetCI>Y PLAY SCRIPT1 FINANCE

NetCI executes a script file called SCRIPT1 on node Y. If you recall our
sample internetwork, node K is the management node. If you also recall,
the script file called SCRIPT1 (refer to "Writing and Executing Script
Files") redirects output to the log file called LOGFILE1. When you
execute SCRIPT1 on node Y with PLAY, the output will be stored in
LOGFILE1 on node K in the operator.sys account.

Example

This example shows logging being activated with input from the keyboard
and output to both the screen and to FILE1. The straight line under
Output Mode in the example indicates when and how long the output is
redirected to the screen and/or to the FILE1. Notice how LOGRESET
returns output back to the screen.

LOG

Redirects the output of a process or operation to a log file.

Syntax
_____________________________________
| |
| LOG file |
_____________________________________

Parameters

file

Name of the file where output is to be stored. This file name is one of
the following fully qualified file names:

* file

* file.group.account

* file reference (allows you to back reference a :FILEcommand, to
reference a previously defined file, or to reference a device such as
a printer)

Discussion

If the specified log file does not exist, the file will be created except
for a back-referenced file which must exist or be defined already.

If the specified log file exists, the new data will append to the end of
the existing file.

If the specified log file is full, a warning message will display. The
default size of the log file is 1024 records. If you will need a log
file with a bigger record size, use the BUILD command to create a bigger
file.

If you are in the MPE mode, a special slash (/) character must precede
the LOG command since NetCI assumes only MPE commands are executed in
this mode.

Example

This example redirects all output to the file called FILE1.

NetCI>LOG FILE1 . .

LOGRESET

Resets NetCI so that output appears only to the screen.

Syntax
_____________________________________
| |
| LOGRESET |
_____________________________________

Example

This example shows how LOG redirects output to a log file called FILE1.
LOGRESET then resets the output back to the screen. If output is not
reset back to the screen, output will continue to be directed to FILE1.

NetCI>LOG FILE1...NetCI>LOGRESET

Scripting and Logging

NetCI redirects both input and output when scripting and logging are used
simultaneously. When output is redirected, remember the following:

1. During execution of the script file, the output mode specified in
the script file is always in effect. If the script file does not
specify an output mode, the mode prior to script file execution
remains in effect.

2. After execution of the script file, the output mode prior to
execution takes effect again.

Input and output determine the operational mode in effect. It is only in
the logging operation mode that output is to both the screen and log
file. Refer to Table 7-2 to determine the input and output applicable to
each mode of operation.

Examples

The following examples begin and end with the interactive operation mode.
Each example shows the operation and output mode in effect at a
particular time. The output can be redirected to either the screen or a
log file, or to both the screen and log file. The straight line under
Output Mode in each example indicates when and how long the output is
redirected to the screen, log file, or both. Notice from the examples
that the scripting operation mode is always in effect whenever a script
file is executing. However, logging mode may not always be in effect.

Table 7-2. Operational Modes

Example 1

This example shows both scripting and logging being activated. Before
execution of the script file, output is to the screen. When you execute
the script file with PLAY, the script file redirects output to FILE1.
After execution, output returns to the screen since this is the output
mode prior to execution. You do not need to specify the LOGRESET
command.

Example 2

This example first shows logging being activated by input from the
keyboard. Output is to the screen and to a log file called FILE1. Since
you may need to interactively respond to the output, it will also be
displayed to the screen. Next, you execute a script file called SCRIPT1
with PLAY. While the script file is executing, input is from the script
file and output continues to FILE1 since the script file has not
redirected the output. The output continues to FILE1 since the user is
not required to interactively respond during execution. The LOGRESET
command then resets the output to the screen. If LOGRESET is not
specified, output will continue to the screen and to FILE1 since the
output modes prior to script file execution take effect.

Example 3

This example first shows logging being activated by input from the
keyboard. Output is to the screen and to a log file called FILE1. Since
you may need to interactively respond to the output, it will also be
displayed to the screen. Next, you execute a script file called SCRIPT1
with PLAY. While the script file is executing, input is from the script
file and output is to FILE1. After script file execution, output returns
to the screen and to FILE1 which are the output modes prior to execution.
At this point, only logging is in effect. Output continues to the screen
and to FILE1 until LOGRESET where output is only to the screen.

Example 4

This example first shows logging being activated by input from the
keyboard. Output is to the screen and to a log file called FILE1. Since
you may need to interactively respond to the output, it will also be
displayed to the screen. Next, you execute a script file called SCRIPT1
with PLAY. While the script file is executing, input is from the script
file and output continues to FILE1 until the output is redirected to
FILE2 with % LOG FILE2. After script file execution, output returns to
the screen and to FILE1 which are the output modes prior to execution.
At this point, only logging is in effect. Output continues to the screen
and to FILE1 until LOGRESET where output is only to the screen.

Sample Applications

The following are sample NetCI applications that you can develop to use
in a production environment. You can write a script file containing
applicable commands, flow control statements, and data that will
automatically perform different operations on multiple remote nodes.

Sample Script
File 1

This application summarizes the network configuration for each node in
NET3 of our sample internetwork. The following script will display all
the entries in the network directory file for the NETXPORT (Network
Transport) subsystem. We will write a script file called GETCONF that
contains NMMGR commands to be executed on each node in NET3. Logging
will also be used to send all output to an MPE log file called ALLCONF.
This log file will be interactively entered with the LOG command before
you execute the script file.

The GETCONF script file contains the following commands:

%file nmmgrcmd=$stdinx reads input from the script file.

%run nmmgr.pub.sys runs the NMMGR configuration program.

opendir nsdir.net.sys opens the network directory file.

listdir displays information on all entries for all
nodes.

openconf nsconf.net.sys opens the current NS configuration
information file.

versionconf "A.02.03" verifies the configuration version.

pathconf=netxport.ni.lan1 specifies the path for the configuration
.protocol.ip file to be read.

readconf displays the network configuration for the
NETXPORT subsystem.

exit exits NMMGR.

We are now ready to execute the script file, GETCONF, on all nodes in
NET3 of our sample internetwork. If you recall our sample configuration
file, node J was deleted from the NetCI configuration. However, we will
assume we have added node J back into the configuration. Now we will
create a list called NET3 that will contain all the nodes in NET3 with
the NEWLIST command.

NetCI>NEWLIST NET3

We will then assign all the nodes in NET3 to this list with the ALTLIST
command.

NetCI>ALTLIST ADD NET3 H,L,K,J,I,Y

We can verify this by entering the SHOWLIST command at the NetCI prompt:

NetCI>SHOWLIST NET3
NET3
Nodes on list:
Y I J K L H

Before executing the script file, we should create a disc file with a
bigger record size so there will be no data overflow. We will use the
BUILD command to create a disc file called ALLCONF with 10,000 records,
each 80 characters long, and ASCII format. Next, we will run NetCI and
redirect all output to be saved in this file with the LOG command.

:BUILD ALLCONF;REC=- 80,100,F,ASCII;DISC=10000
:RUN NETCI.PUB.SYS

To execute the GETCONF script file, enter

NetCI>LOG ALLCONF
NetCI>NET3 PLAY GETCONF
ALLNODES>/LOGRESET
ALLNODES>/EXIT

The script file will be executed sequentially on all the nodes in NET3.
After the script file is executed, we can then print the logfile,
ALLCONF, to view the network directory and configuration file information
for all the nodes in NET3.

Since it is likely that the script file will take awhile to execute, you
may want to create a job stream to execute it.

Sample Script
File 2

This application shows how to install a new version of software and to
convert existing files for use with this new software. We will write a
script file, INSTALL, that copies the file, PROG, and the conversion
program, CONVERT, to a new group, NEWVERS, at each node in NET3. We will
then execute the CONVERT program to convert the file (PROG.NEWVERS).
After the conversion, we will purge the old file in the APPLIC group
(PROG.APPLIC) and rename the new converted file to the same file name and
group as the old file. You can use NetCI to perform this task using one
script file, INSTALL, and the PLAY global command.

The INSTALL script file contains the following commands:

%dsline local=!1 file equation for the node defined as local.
The referenced node will be specified with
the PLAY command.

%newgroup newvers creates a new group called newvers on the
node.

%dscopy runs the DSCOPY subsystem.

prog.newvers:local specifies that the target file will have the
[operator.sys] to same file name as the source file. REP
@.NEWVERS;REP option replaces the existing file in the
destination node with the new file if a file
with the same name exists.

convert.newvers:local same as the previous explanation.
[operator.sys] to
@.NEWVERS;REP

// exits DSCOPY.

%run convert.newvers executes the CONVERT program to convert the
PROG file.

%purge convert.newvers purges CONVERT program file on target node.

%purge prog.applic purges old existing file in the APPLIC group
on target node.

%rename prog.newvers,prog. renames converted file on target node to the
applic same file and group name as the old file.

%purgegroup newvers purges the newvers group on the target node.

yes response to the question verifying that the
newvers group is to be purged.

%run prog.applic;info= checks that the converted file has been
"showversion" converted for use with the new version of
software.

%tellop...**applic: displays a message that the current software
version a.01.01 installed & version has been successfully installed and
ready** is ready for use.

We are now ready to execute the script file, INSTALL, on all nodes in
NET3 of our sample internetwork. If you recall from Sample Script File
1, all nodes in NET3 are members of the list called NET3.

To execute the INSTALL script file, enter

NetCI>NET3 PLAY INSTALL H

If you specify the output to a log file, you can later scan the file for
errors. Additional MPE statements can be added to provide for more
robust error checking such as the handling of unexpected errors. For
example, if someone is running the application, the :PURGE command will
fail. We can use MPE commands such as :IF or :ELSE to also modify the
execution of the script file.

Sample Script
File 3

This application shows how you can create a script file containing a job
stream for the nodes in NET3 of our sample internetwork. The following
script will contain the :STREAM job command for the different nodes.
When you execute the script file called SYSCONF, this will stream a job
file called CONFJOB which will then execute the SYSINFO program (which
lists the configuration information for the node).

All the commands in the CONFJOB job file may also be included in a script
file. However, we will assume you already have an existing job file that
contains these commands. You only need to create a script file to stream
the job file. By streaming an existing job file within a script file,
you do not need to type again all the commands from the job file into the
script file, and you can always run the job file in MPE.

The SYSCONF script file contains the following stream command:

%stream confjob.util.sys streams a job on a node.

Although the script file contains only one
command line, it is sometimes easier to
enter PLAY SYSCONF than entering the entire
command line.

The CONFJOB job file contains the following commands and data:

!job net3,operator.sys/net3k;hipri;pri=cs;outclass=epoc,13
!comment this will print the system configuration report

!file conflist=sysinfo;dev=pp;env=elite.hpenv.sys

!run sysinfo.prv.telesup

out pp

title "NET3"

all

exit

!eoj

The job file, CONFJOB, will run a program on the node or list that you
specify with the PLAY command. This program called SYSINFO will generate
a report listing the node's configuration. The configuration includes
the devices on the system, other system information such as MPE tables,
program stack size usages, directory usage, system logging, user logging,
spooling, virtual memory, GIC hardware configuration summary, data
communication device summary, and so forth.

To execute this script file against all the nodes in NET3, we will
execute the SYSCONF script file on the previously configured list named
NET3. To execute this script file, enter

NetCI>NET3 PLAY SYSCONF

This will stream the job for each node in NET3. When the job is
completed for nodes Y, I, J, K, L, and H, the configuration listing will
be sent to the printer.

Example

The following example shows how you can also create a script file which
can be executed on each node/list instead of a script file containing a
job stream. We will write a script file called NODCONF that will execute
the SYSINFO program on the node that you specify with the PLAY command.
Logging will be used to send all output to a log file called REPORT.

The NODCONF script file contains the following commands:

%/log report redirects output to logfile called REPORT.

%run sysinfo.prv.telesup executes program.

title"NET3" information required by program.

all information required by program.

exit exits program.

%/logreset resets output back to the screen.

We are now ready to execute the script file, NODCONF, on any node. For
example, to execute the script file on node L, enter

NetCI>L PLAY NODCONF

which will generate the system configuration listing for node L.

To execute the script file on all nodes in NET3, enter

NetCI>NET3 PLAY NODCONF

which will generate the system configuration listing for NET3. The
listings for node L and NET3 will be in the REPORT log file residing on
node K which is the management node.

Sample Script
File 4

This application shows how you can create a script file called SYSOP
containing operations or jobs to be run at a particular time. The
following script file shows how you can effectively use flow control
commands to control the execution of these operations or jobs to be run
at particular times.

The SYSOP script file contains the following commands:

%/while hour < 24

% /comment The following operations are done between 8am and 5pm.
% /if hour > 7 % /if hour < 18 % showjob job=@j
% /else
% /comment This operation is done only at 8pm.
% /if hour = 20
% showjob job=@s
% /endif

% /comment At 10pm the following operation must be done.
% /if hour = 22
% listf @ipc@.maildb.hpoffice,2
% /endif
% /endif
% /endif

% /inc hour

% /comment Replace v in the following statement with the remaining
% /comment number of seconds until the next approximate hour.
% /wait v

%/endwhile

We are now ready to execute the script file, SYSOP, on any node. Before
we execute the script file, we must interactively assign a value (the
current time) to the variable called "hour". To set the current time,
enter

NetCI>LET HOUR=X (X is current hour,
for example, 6 for 6 A.M.)

After specifying the current time, we are now ready to execute the SYSOP
script file. To execute this script file, enter

NETCI>NET3 PLAY SYSOP

to run particular operations at specified times on all the nodes that are
members of the NET3 list.

If you are executing the script file on a list, you should change the
wait duration to a value that will allow the file enough time to execute
on all nodes during each hour. For example, if it takes approximately
1200 seconds to execute the script file on all nodes that are members of
the NET3 list, you could assign 2400 seconds as the wait value. This
would be enough time for execution to have occurred on all the nodes.
The script file will take about 1200 seconds to execute and then wait
2400 seconds to execute again. This will be approximately the next hour.

MPE/iX 5.0 Documentation