Suprtool

MPE Quickstart for Unix Users

Based on the technical support calls that we are receiving, it appears that many HP 3000 systems are being put in the care of staff with only Unix and Windows. So we have decided to write a series of introductions to MPE for these lucky souls:

Part 1: Command Cross-Reference

Part 2: Login and Logoff

Part 3: Files

Part 4: File Content

Part 5: Scripts


MPE for UNIX Users, Part 1

Cross Reference from Unix Commands to MPE Commands

First thing you need to know is that MPE has Unix-like features integrated into it (via Posix), but most applications and software tools were written with the non-Posix features.

Basic MPE consists of a single shell (the command interpreter) and a file system that has only 3 levels (user, group, account) but has many file attributes including record size/type, max file size, extents and passwords (called lockwords).

The 3rd party product MPEX is an alternate shell, as is sh.pub.sys (the Posix shell).

(This cross reference list below is adapted from an inverse list by Neil Armstrong of Robelle.)

UNIX Command Equivalent MPE Command
sh command interpreter, mpex or posix shell
ksh command interpreter, mpex or posix shell
csh command interpreter, mpex or posix shell
.profile (sh) option logon in UDC
ksh $r, csh %! while do, do until
< file (input) < file
> file (output) > file
>> file (append) >> file (append)
<< hereis doc Not supported
scriptscommand files, udc


# at start of line comment
command & Not supported, use job
cmd1 && cmd2 Not supported
$r(ksh),%!(csh) redo
x=v;export NAME setvar


abortjobkill [-9] abortio
adduser newuser
at stream
batch stream
cancel deletespoolfile
cd chdir
chmod, passwd altacct
chmod, passwd altgroup
chmod file altsec file
chmod, passwd altuser
cp copy
cpio store
date showtime
dc calc
df, bdf discfree, dstat
du diskuse,report
echo echo,r print
ed editor, quad or qedit
env showvar
exit bye, exit, eoj
fbackup (hp-ux) store
fc -1 (sh) listredo
fi endif
ftp ftp, dscopy
if then else if then else
history listredo
hostname showme
login hello, job
logname showme
kill [-9] abort
ld linkedit
lpq showout
lprm deletespoolfile
lpstat showout
ls listf, listfile
man help
mesg -n set msg off
mkdir newdir,newacct,newgroup
more print
mv rename
printenv showvar
ps showproc, showq
pwd pwd
rwall warn
reboot -h =shutdown
rm purge
rmdir purgegroup,purgeacct
sed editor, quad, qedit
setenv setvar
su god (3rd party vesoft)
symbolic link file equation, posix link
tar store
touch build
unset,unsetenv deletevar
users showjob
vi qedit
wall warn
whence help
whoami showme
while...do...done while do endwhile
write tell


MPE for UNIX Users, Part 2

HP 3000 Login and Logoff

By Robert Green, Robelle

So you are an experienced Unix/Windows SysAdmin who has been given the responsibility of looking after your firm's network of HP 3000s. And you have never seen the MPE operating system before.

One of the first things that you might do is log onto one of the systems, using the login instructions and passwords left you by the previous administrator.

Supposed you find the old admin's PC and on the desktop are icons for "PROD3000 Session" and "TEST3000 session". If you don't find these icons, look for a program called Reflection, or Minisoft, or QCTerm. These are all software emulators for the classic HP 2392/700-92 terminals. Within the emulator, look for "Connect" in the menus and look for a list of server names.

(You can also connect to the 3000 with generic Telnet, but some capabilities will be lost.)

Let's click on the "Test" connection first! No need to experiment on what is probably the production system.

You should see a window that looks like a classic 24x80 computer screen. Then a colon should appear in the window with the cursor after it. This is the MPE command prompt).

:
You are being prompted for login, just like the login user prompt on Unix, except that in this case you need to type a Hello command.
:hello mgr.product
The command name is "HELLO", which means start an interactive session.

The User name is "MGR"; user names not like Unix user names.

The Account name is "PRODUCT", to which the User belongs.

You will usually be prompted for one or more passwords (the account can have a password and the user can also have a password). If you enter them correctly, you will see the colon (:) prompt again - you are logged on. Unlike most versions of Linux and Unix, you CAN use the backspace key in order to make corrections.

Enter the Showjob command to see that you are listed and see what other user sessions are active.

:showjob

Pre-entering Passwords - Say the Account password is "xyz29b". You can enter it in response to the system prompt, or you can embed it in the Hello command, using a slash between the account name and the password.

:hello mgr.product/xyz29b
Typically when logging on, most users let the system prompt them for the password as this is not echoed to the screen.

User Names - User and account names are limited to 8 alphanumeric characters and must start with an alpha. User names and commands are not case sensitive (i.e., mgr = MGR = Mgr). User names are not system wide as in Unix. They are only unique to an Account. For example, MGR.DEMO is a completely different user from MGR.PRODUCT. MGR is not a unique user name, but MGR.PRODUCT is unique.

Accounts can have many user names, such as BOB.PRODUCT, BILL.PRODUCT, SALLY.PRODUCT, but often accounts only have one User.

Why is that?

Because certain system functions, such as File Rename, can only be done by the user who originally built the file (the Creator this is called). If you have multiple Users in an Account, you sometimes have trouble performing all the file tasks you wish to perform. For example, you logon as BILL.PRODUCT and rebuild a production file (you can Purge the file without being the Creator, but when you build the new file you are now the new Creator). Then a nightly production task logs on that night as BOB.PRODUCT and tries to rename the file. It fails because it is not the Creator and the task fails as well, causing operational problems in the morning!

An Alternative to Users

There is an alternative to having several User names for an Account: use Session names instead.

:hello bob,mgr.product
The session name is "BOB" and it will show up on the Showjob command, but doesn't mean much of anything else. But all files in the PRODUCT account will be created by user MGR and can be renamed by any session name that can login as MGR. So everyone would login as MGR, but with a unique Session name.

Except! Vesoft has a 3rd party Security/3000 product that can create passwords on the Session name. This very useful, especially since the Vesoft Session names can be applied to any account if you like. In effect, this creates something like a Unix user name that is mostly independent of file directories (yes, Accounts are also file structures in MPE).

File Storage in Accounts and Groups

Your account also provides file storage. MPE files are stored in Groups, which are like sub-directories of Accounts. Unlike Unix, MPE files are not stored at the Account level, but only at the lower Group level (and there are no sub-Groups; sorry!)

For example, the PRODUCT account might have four groups:

PRODUCT account

PUB group - this is a default group that all accounts have
DATA group
TEMP group
JOBS group
PROGRAMS group
Again, Group names are limited to 8 characters and are not case sensitive.

And of course there can be passwords on each Group, just as there can be on each Account and User. Security access restrictions are attached to Accounts and Groups (such as "only someone who can login to the Account can read the files in this Account).

Each user can have a default logon group. When you logon you can see the files in your logon group using Listf or Listfile:

:LISTF  - shows the MPE files in your current group
:LISTFILE - shows MPE and POSIX files in your current group 
You can specify a different logon Group after the Account in the Hello command
:hello mgr.product,jobs
There is one thing that is quite confusing for new users. In the Hello command, the Group comes after the Account, separated by a comma. But in a file name, the Group comes between the file name and the Account, separated by periods. For example,
MGR.PRODUCT,DATA
User.account,group

SALES2004.DATA.PRODUCT
File.group.account
To make things a bit more complex, the trailing Account and Group names can be left off from a file name and will default to your current login Account and Group.
SALES2004.DATA - in your logon PRODUCT Account
SALES2004 - in your logon DATA group of the PRODUCT account
These are all the same file.

Mapping MPE Files into Posix Space

Since MPE also has Posix files, how does the MPE file system map into the Posix structure? It is actually quite simple. All MPE names are converted to uppercase.

/PRODUCT  - the Account is located off the Root node 
/PRODUCT/PUB - the default "PUB" Group
/PRODUCT/DATA - the DATA Group
/PRODUCT/DATA/SALES2004 - a file in the DATA group
Effectively, the MPE Account is treated as a root directory on Posix, with the Groups treated as sub-directories of the Account. Very neat - in fact, the system allows Posix files to be created within MPE Account/Group space, but those files cannot be "seen" by ordinary MPE commands such as Listf (only the new commands such as Listfile).

Help Yourself

Instead of "man" pages on Unix or F1 in windows or other help files, MPE has it's own Help facility, which can be accessed by:

:help
That is enough for your first time on MPE. Logoff now with the Bye command.
:bye


MPE for UNIX Users, Part 3

The Complex World of Files

By Robert Green, Robelle

In part 2, we explored the directory structure of MPE a bit to explain about logging on. In part 3, we look at files to see how they are different from files in Unix.

The File System is one area where MPE is really different from Unix. And much more complicated. Let's start by building a file,

:build abc
Seems just like touch abc in Unix, right? Wrong - the build command has lots of optional parameters, all with defaults.

To see what we "built", we use the listf command (this is like ls -l in Unix):

:listf abc,2
ACCOUNT=  GREEN       GROUP=  BOB     

FILENAME  CODE  ------------LOGICAL RECORD-----------  ----SPACE----
                  SIZE  TYP        EOF      LIMIT R/B  SECTORS #X MX

ABC               128W  FB           0       1023   1        0  0  *
The listf,2 option shows the most common attributes of an MPE file. Other options show access dates, creator name, and other attributes.

FILENAME - file names are limited to 8 characters and case is not significant; just as explained for user and account names in part 2.

CODE - a file type number that tells you what type of content the file should hold. Some of these have mnemonic labels, but underneath all are integer values. For example, 111 is a QEDIT workfile, 1030 is an NMPROG file. The default code is 0 (i.e., nothing special). For a list of file codes used by HP and third-party vendors, go to

http://www.robelle.com/smugbook/filecode.html
A negative file code makes the file a "privileged file" which can only be opened by a program running in privileged mode (in user mode, programs cannot access or change data that is not their own; in privileged mode, programs can get at data outside the program; the operating system runs in a special privileged mode). The most well known example of privileged files in MPE is database files; they can only be accessed by going through the database API (or by going into privileged mode, access to which is restricted by system security).

SIZE - specifies the record size. Unix files do not have records; a file is just a stream of bytes. But MPE files have a record structure (except for Posix bytestream files, which are like Unix files).

The record size is the amount of data that is read or written by a single call to MPE's FREAD or FWRITE intrinsic. An intrinsic is an MPE system routine, just like fread and fwrite in Unix.

The default record size is 128 words (which is 256 bytes, because the original HP 3000 was a 16 bit machine).

TYP - FB means "fixed, binary". Fixed is the record format, meaning that each record contains exactly 128 words. Another option is V for Variable. Binary means that if a fixed record is incomplete, it is filled out with binary zero. The alternative A for Ascii means that incomplete records are filled with blanks. Also, when a file is Ascii, the SIZE column will show the record size in Bytes (128B for example).

EOF - tells you how many logical records have been written into the file (actually, it shows you the highest record number that has been written). An empty file like this always shows 0 for the EOF.

LIMIT - tells you the maximum number of logical records that can be written into the file (for variable length records this number is based on writing maximum length records, so it is often not the real limit). The LIMIT concept is completely alien to Unix. In MPE, a program can fail because it attempts to append a record to a file that has reached its LIMIT, even though the system still has lots of free disk space.

R/B - Records Per Block. In the original MPE you specified the number of logical records to be stored in a physical block of disk storage (a block was the amount normally transferred to/from disk). Over the years, the internals of MPE have changed so much that this attribute does not mean much anymore, although it is maintained for compatibility.

SPACE, SECTORS - Logical disk space in MPE is measured in "sectors", which are 256 bytes each. As records are written into a new file, disk space is allocated in chunks called "extents" and this SECTOR value goes up. Again this unit of measure is just for historical compatibility, since the current version of MPE actually manages disk space in pages, which are much larger. If you would like more explanation, please see

http://www.robelle.com/smugbook/pages.html
SPACE, #X MX - disk space is allocated in extents, so #X is the number of extents currently allocated to the file and MX is the maximum number that can be allocated. In the old days, MX was limited to 32 and #X went from 0 to 32, at which point the file was full. And all extents, except the last one, were the same size.

Now the default MPE file has * for MX, which means that there is no effective limit on the number of extents. However, you still must have a fixed number for the LIMIT on logical records, even if that number is 2 billion!

Be warned that if you create a file with a fixed number of extents and a large LIMIT in logical records (for example, build def;disc=123456789,32), you may very well get an error such as "extent size too large".

Here are some additional file attributes for MPE:

USER LABELS are optional 256 byte areas for control information that are tacked onto the start of the file space. Typical examples are Self-Describing files and Powerhouse subfiles, where the data dictionary is stored in the user labels; this leaves all the logical records with the same data format. Historically they come from old mainframe systems, even going back to tape-based systems where the tapes had labels on them! They are most commonly used in COBOL systems that were migrated from these old IBM systems. The typical file on MPE has 0 user labels.

CCTL - stands for Carriage Control. A file with the CCTL attribute has an extra byte at the beginning of each logical record which tells whether to do a page eject, single space, double space, or more obscure function before (or after) printing the record. These are not the same as Spool files; they are more like antique portable print files. This capability goes back to old line printers, which had program tapes, which could be customized for special forms such as pre-printed invoices. What is interesting is that most of MPE's simulated line printer functionality still works on Deskjet printers and terminal screen emulators because MPE converts the CCTL codes into terminal codes.

The default for an MPE file is build abc;nocctl. For more on CCTL files:

http://www.robelle.com/smugbook/cctl.html
TEMP - stands for temporary files. On Unix, temporary files are just permanent files that are built in a special directory, such as /var/temp. Unix does not normally have an automatic cleanup for temporary files after a user logs off. MPE temp files are different because they are actually temporary! They are not recorded in the regular file directory, but in a temp directory that is attached to the user logon (interactive session or batch job). Any process created during the logon can access the temp files of that session/job and when the session/job logs off, the temporary file space is returned to the system.

MPE even has process-temporary files that are private to a program and go away when that process terminates or aborts. These are called NEW files and can be saved as Temporary or Permanent files by the process.

CIR, MSG - stands for Circular or Message file. MPE has special files where the current record pointer either wraps around (CIR) or moves in such a way that a fread erases the record that is read (MSG).

KSAM, KSAMXL - these are indexed sequential files, with KSAM being the original, classic MPE version and KSAMXL being the rewrite for the RISC processors and MPE/XL (now called MPE/iX).

So, you can see that our simple build abc is actually a much more complex command:

:build abc;rec=128,1,F,binary;disc=1024;code=0; &
std;ulabel=0;nocctl
Tune in next month for details on how to work with the content of all these file types!


MPE for UNIX Users, Part 4

Examining the Content of Files

By Robert Green, Robelle

In part 3, we looked at files. In part 4, we learn how to look at file content.

If you are a Unix person, the first thing you look for is more, and the MPE equivalent is Print:

	
    Print filename
Print displays the lines of the file on $Stdlist, stopping every screenful and asking if you want more. You can answer Y or N. In Unix, you usually press Space for Yes or "go on", but in MPE you usually press Enter.

Print is only useful for files of text data. For looking at binary data, the basic tool provided by MPE is Fcopy.

The main purpose of Fcopy is "file copy", but it can also display binary data in Hex or Octal format and do some simple data selection. Fcopy is a subsystem, while Print was an MPE command. You enter the subsystem with the Fcopy command and it has its own commands. You exit the subsystem with the Exit command (some later subsystems used Quit as Unix started to influence MPE). Other subsystems of MPE include Editor and Sort.

    :fcopy
    >from=filename;to=;hex;char
    >from=filename;to=;octal;char 
    >exit
    :
Notice that when you enter Fcopy, the prompt character changes from Colon to Greater Than. This is typical - a Colon prompt always indicates that an MPE command is expected.

The first command displays each record of filename on $Stdlist as a hexadecimal dump and as a character dump (Char replaces nonprinting characters such as Carriage Return and Linefeed with Period to avoid disrupting your display).

The second command converts the record data to Octal instead of Hex.

The third command, Exit, gets you back to MPE.

Fcopy introduces you to a couple of other MPE-isms.

1) You use Control-Y to stop the listing; this is true for all MPE subsystems, but for MPE commands use the Break key if Control-Y does not work.

2) The syntax of the Fcopy commands is different from that of MPE commands; unfortunately, this is true of most all MPE subsystems-they all have slightly different command syntax styles.

Fcopy also allows you to select specific records numbers, or records that have a specific text string at a given location. You append the Subset option to your copy task:

    subset=1/10
    subset="string", column  [,EXCLUDE]
But Fcopy cannot select on binary fields or look for multiple strings.

For complex text searches, the Unix user turns to grep, and MPE has grep in the Posix shell. To enter the shell, you type "sh.pub.sys", which is an implied run on the "sh" program in the "pub" group of the "sys" account. When you are in the Posix shell, you must use Posix filenames, not MPE filenames. So sh.pub.sys would be /SYS/PUB/SH.

For looking at file contents, the Posix head and tail commands are very handy (show the start of a file or the end of it).

Another MPE subsystem that can be used for examining text files is Editor.

    :editor
    /text filename
    /find "string"
    /list *
    /exit
Notice that the prompt character is Slash, while Fcopy used Great Than.

Editor has a fairly powerful set of search options. In this example, Find looks for the next line that contains the string at any location within the line. But to find all the lines that match, you must program the Find in a While loop.

MPE also has a wide variety of text tools from third-parties that you will likely on your system, such as Qedit, an Editor replacement that also provides full-screen editing (see www.qedit.com).

     :qedit.pub.robelle
     /text filename
     /list "string"
     /exit
The commands are similar to Editor, but the default behavior is to treat any occurrence of a string as a request for all the lines that contain that string. Qedit borrows concepts from Fcopy and other tools. For example, you can display the selected lines in Hexadecimal if you wish:
    /list $hex $char 1/10
Or ignore case and only search certain columns on string matches:
    /List "enhancement" (Upshift 20/50)
Or search for up to 10 strings on a single command.
    /List "problem" or "bug" or "help"
Magnet is our method of choice for searching a group of files, because it is so fast. It is a part of "Nuggets (aka Toolboxes)", a package of MPE utilities written by Stan Sieler and friends, and sold by Lund. By default, Magnet lists the files with a filecode of zero (regular files) or 111 (Qedit files) in your logon group that contain at least one line with the target string. Use the -F option to specify filesets, the -C option to ignore case, -L to list lines that match, and -E to show Editor-style line numbers. For example, to search the SRC group of the logon account for "fopen", ignoring case:
    :magnet "-f@.src fopen -c -l -e"      
For more details on Magnet, see
    http://www.allegro.com/products/hp3000/toolboxes.html
MPEX is a third-party tool from Vesoft that extends the MPE command shell to work on sets of many files, rather than just one file. It is very flexible and allows selections such as "files bigger than 1 GB and untouched in over a year". MPEX allows you to select files based on searching text within the files:
    %PRINT AP@.SOURCE;SEARCH="CUSTNUM";NUM
MPEX also allows searching for lines containing alternate strings, or more than one string, or almost any search logic:
    %PRINT @.SOURCE;SEARCH="PROCEDURE" or "FUNCTION";NUM
    %PRINT @.SOURCE;SEARCH="PROCEDURE" and "FNAME"
    %PRINT @.JOB;SEARCH="!JOB" and NOT "MANAGER.SYS"
There are many more options (case-less, look for delimiters, look for a delimiter on the left only, etc.).

Database Files

What does it mean when you get this error:
    :print store01.db
             ^
    PRIVILEGED FILE VIOLATION  (FSERR 45)
    The PRINT command failed. (CIERR 9080)
This means is that you tried to open a database file in user-mode. These are "privileged files" that can only be opened in Priv Mode. This restriction ensures the integrity of the database structure by forcing all access through system-approved tools or APIs.

Query is a database tool found on every HP. It can do selection, but only works on databases, not disk files. A simple Query task would be:

    :query
    >FIND order-detail.order-date GT 20040101 
    >REPORT ALL
Query has numerous report formatting options, including sorting, level breaks, item formatting, etc. However, the output is intended for a printer, so most of the formatting options have that in mind. It is possible to redirect this output to a disk file, but Query was written before anyone asked for output to an Excel spreadsheet.

Suprtool is a third-party product (see www.suprtool.com) that is found on many HP 3000 systems; it works on both databases and disk files. Like Fcopy it can copy or print records using Char,hex dump, but it can do much, much more. It can do sophisticated selection and sort the records. For example, to select all the Open orders, sort them, eliminate duplicates, write them to a disk file for further processing, and print the fields of each selected entry, use:

    :suprtool.pub.robelle
    >base orders.db
    >get order-detail
    >if order-date > "20040101" and order-status="O"
    >sort order-num
    >dup none
    >output opensel
    >list
    >xeq
Suprtool provides a Define and Item command to describe the record format of a file so that it can be treated like a database. Or to more accurately describe a database (i.e., define sub-fields, date fields, and decimal places). The output can go to the printer, or to a disc file, or to the database, or to an Excel spreadsheet, or to almost any other format of file.


MPE for UNIX Users, Part 5

Shell Scripts

By Robert Green, Robelle

Both MPE and Unix have scripts, but there are a number of differences. From a paper by Ken Robertson when he was at Robelle:
"Before MPE/iX, there was a run-time environment for the MPE/V class of HP computers called the Command Interpreter (CI). This MPE/V CI had limited programming capability, with If / Else constructs and numeric variables limited to values between 0 and 65535. The basic interface of the MPE/V CI (Command Interpreter) was ported to MPE/iX machines, and beefed up so it would be usable as a run-time shell.
The MPE/iX command interpreter has a generous command set, pushing the shell into the realm of a true programming tool. Its ability to evaluate expressions and to perform I/O on files allows the end-user to perform simple data-processing functions. The CI can be used to solve complex problems. Its code, however, is interpreted, which may cause a CI solution to execute too slowly for practical purposes.

Command files are a collection of commands in flat files, of either variable or fixed length record structure, that reside in the MPE or POSIX file space. Basically, command files are what you could call MPE Macros. Anything that you can do in the CI interactively, you can do with command files, and then some. You can use command files in situations that call for repetitive functions, such as re-compiling source code, special spooler commands, etc. Command files are also great when you want to hide details from the end-user.

A command file is executed when its name is is typed in the CI, or invoked from a command file or programming shell. Just as in program execution, the user's HPPATH variable is searched to determine the location of the command file."

MPE Scripts Versus Unix Scripts

For the average task, the MPE scripting language is easier to read and understand than most Unix scripts. For example, command line parameters in MPE have names, just like in regular programming languages.

Of course, there are several script languages on Unix and only one on MPE! On Unix you can write shell scripts for any of the many shells provided (C shell, Bourne shell, ksh, bash, etc). Although there is also now a Posix shell on MPE, most scripts are written for the CI. Several third-party tools, such as Qedit and MPEX, emulate HP scripting and integrate it with their own commands.

A command file can be as simple as a single command, such as a Showjob command with the option to only show interactive sessions (and ignore batch jobs):

   :qedit
   /add
          1    showjob job=@s
          2    //
   /keep ss
   /e
   :
You have created a command file called SS -- when you type SS you will execute showjob job=@s

On MPE, the user needs read (r) or execute access (x) to SS. On Unix you normally must have x access, not just r access, so you do a chmod +x on the script. This is not necessary in MPE, although, if don't want users to be see the script, you may remove read access and enable execute access.

Structure of a Command File (aka CI script)

A script is an ASCII file with maximum 511 byte records. Unlike Unix, the records may contain an ASCII sequence number in the last 8 columns of each line. The command file consists of 3 optional parts:

1. Parameter line with a maximum of 255 arguments

    parm sessionnumber
    parm filename, length="80"
2. Option lines
	option nohelp,nobreak
	option list
3. The body (i.e., the actual commands)
	showjob job=!sessionnumber
	build !filename;rec=-!length,,ascii
In MPE scripts, there is no inline data, unlike Unix 'hereis' files.

Parameters

Notice in the example above that parameters are used with an exclamation (!), as opposed to the $ in Unix. The same is true for variables. Parameters are separated by a space, comma or semicolon. All parameter values are un-typed, regardless of quoting.

In a typical Unix script, the parameters are referenced by position only ($1, $2, $3, ...). In an MPE script, the parameters have names, as in the function of a regular programming language, and can also have default values. In Unix you use $@ for all of the parameters as a single string; in MPE you use an ANYPARM parameter to reference the remainder of the command line (it must be the last parameter).

Here is a script from Beechglen to translate "subsys" and "err" numbers from MPE intrinsics into error messages. The subsys and error numbers are passed in as parameters:

parm p_subsys=108,p_error=63                                            
comment decodes subsys and info error codes.          
comment By Mike Hornsby from Beechglen Development.         
comment Thanks to Stan Sieler from Allegro.                
comment                                                                 
setvar subsys hex(!p_subsys)                                            
setvar error hex(!p_error)                                              
comment the hex conversion allows for negative numbers                  
comment the #32765 is  magic  according to Stan!                        
setvar cmd "wl errmsg(#32765,!subsys);wl errmsg(!error,!subsys);exit"   
debug !cmd
As you can see above, the Setvar command assigns a value to parameter or to a new variable. But there are also system pre-defined variables. To see them all do Showvar @;hp. To get information on variables, do help variable and to get help on a specific variable, such as "hpcmdtrace", do help hpcmdtrace (set TRUE for some debugging help).

In most MPE commands, you must use an explicit exclam ! to identify a variable:

	build !filename
However, some MPE commands expect variables, and thus do not require the explicit !. For example, Setvar, If, ElseIf, Calc, While, and for all function arguments, and inside ![expressions].

Warning: variables are "session global" in MPE. This means that if a child process, or scripts, changes a variable, it remains changed when that child process terminates. In Unix you are used to the idea that the child can do whatever it likes with its copy of the variables and not worry about any external consequences.

Of course having global variables also means that it is much easier to pass back results from a script! And this is quite common in MPE scripts.

Options

Options allow you to list the commands as they are execute (option list), disable the Break key (option nobreak), enable recursion (option recursion), and disable help about the script (option nohelp).

The Body of the Script

Here is a script body that shows active process information (from Beechglen):
WHILE HPCONNSECS > 0                                                    
   IF FINFO("SQMSG",0)                                                  
      PURGE SQMSG,TEMP                                                  
   ENDIF                                                                
   BUILD SQMSG;REC=-79,,F,ASCII;TEMP;MSG                                
   FILE SQMSG=SQMSG,OLDTEMP                                             
   SHOWQ;ACTIVE >*SQMSG                                                 
   SETVAR PINLIST ""                                                    
   WHILE FINFO("SQMSG",19) <> 0                                         
        INPUT SQLINE < SQMSG                                            
        IF POS("#",SQLINE) <> 0 THEN                                    
          SETVAR PIN RTRIM(STR(SQLINE,47,5))                            
          SETVAR PINLIST "!PINLIST" + "," + "!PIN"                      
        ENDIF                                                           
   ENDWHILE                                                             
   IF FINFO("SPMSG",0)                                                  
      PURGE SPMSG,TEMP                                                  
   ENDIF                                                                
   BUILD SPMSG;REC=-79,,F,ASCII;TEMP;MSG                                
   FILE SPMSG=SPMSG,OLDTEMP                                             
   SETVAR PROC "SHOWPROC PIN="+"!PINLIST"+";SYSTEM >*SPMSG"         
   !PROC                                                                
   WHILE FINFO("SPMSG",19) <> 0                                         
        INPUT SPLINE < SPMSG                                            
        IF POS(":",SPLINE) <> 0 THEN                                    
          ECHO !SPLINE                                                  
        ENDIF                                                           
   ENDWHILE                                                             
   PAUSE 30                                                             
ENDWHILE                                                                
This example shows many of the commands commonly used in scripts: If, While, Pause, Setvar, Input and Run. Other commands you will see are Echo, Deletevar, Showvar, Errclear

Handling Errors

In most Unix scripts, if a step fails, you check for an error with an If-conditional and then take some action, one of which is ending the script. Without an If, the script continues on, ignoring the error.

In MPE, the default action when a step fails is to abort the script and pass back an error. To override this default, you insert a Continue command before the step that may fail. You then add If logic after the step to print an error message and perhaps Return (back 1 level) or Escape (all the way back to the CI).

     continue
     build newdata
     if cierror<>100 then
        print "unable to build newdata file"
        print !hpcierrmsg
        return
     else
        comment - duplicate file, okay
     endif
You can set HPAUTOCONT to TRUE to continue automatically in case of errors, but this can be dangerous. The default behavior at least lets you know if an unexpected problem occurs.

User Defined Commands (UDC)

UDCs are like Command File scripts, except that several are combined in a single "catalog" file. They are an older feature of MPE, so you may see them in older applications even when scripts seem like a better solution. The primary reason that they are still useful is that they support Option Logon, which invokes the command when a user logs onto the system.

More Information

Tim Ericson's collection of UDC's and Command files has recently been resurrected and re-published in the public domain at:
http://www.3k.com/index_cmd.html
The Beechglen web site has a number of useful scripts, some mentioned above:
http://www.beechglen.com/mpe/downloads.html