MPEX Help

                                 MPEX / 3000

                                  User Manual

                                 (Version 26.)

                              Copyright (C) 1980
                             Current printing 1997


Eugene_Volokh_1
Eugene Volokh
                           Written by Eugene Volokh
                    Vice President, Research & Development


VESOFT_address_2
VESOFT address


Technical_Support__3
Technical Support
                                 VESOFT, Inc.
                             1135 S.  Beverly Dr.
                        Los Angeles, CA 90035-1119 USA
                             Phone (310) 282-0420
                              Fax (310) 785-9566

DISCLAIMER

The information in this document is subject to change without notice.  VESOFT,
Inc.  makes no warranty of any kind with regard to this material, including,
but not limited to, the implied warranties of MERCHANTABILITY and FITNESS FOR A
PARTICULAR PURPOSE.

VESOFT, Inc.  shall not be liable for errors contained herein or for incidental
or consequential damages in connection with the furnishing, performance, or use
of this material.

(You may purchase additional copies of the manual directly from VESOFT, or
VESOFT's representatives.)

This manual was formatted with PROSE, Robelle Consulting, Ltd.'s excellent text
formatter.  Thanks to Robelle for allowing us to use it.

This section describes the various printing conventions used in this manual to
describe the MPEX product and usage.

Notation       Usage and examples

UPPERCASE      Within syntax descriptions, characters in uppercase must be
               entered in exactly the order shown, though you can enter them in
               either uppercase or lowercase.  for example:

               SHOWJOB

               Valid entries:   showjob   Showjob   SHOWJOB

               Invalid entries: shojwob   ShoJob    SHOW JOB

Italics        Within syntax descriptions, a word in italics represents a
               formal parameter or argument that you must replace with an
               actual value.  In the following example, you must replace
               filename with the name of the file that you want to release:

               RELEASE filename

Punctuation    Within syntax descriptions, punctuation characters (other than
               brackets, braces, vertical lines, and ellipses) must be entered
               exactly as shown.  Note that the "%" shown at the beginning of
               any command should NOT be entered as part of the command, it is
               simply being included to remind you that this is an enhanced
               MPEX command and not a normal MPE command.

             Within syntax descriptions, braces enclose required elements.
item|item    When several elements are separated by vertical lines, you must
               select one and only one of the items specified.  In the
               following example, you must select on or off:

               SETMSG  ON | OFF

[   ]          Within syntax descriptions, brackets enclose optional elements.
               In the following example, brackets around ,TEMP indicate that
               the parameter and its delimiter are optional:

               PURGE filename [,TEMP]

[ ... ]        Within syntax descriptions, a horizontal ellipsis enclosed in
               brackets indicates that you can repeatedly select elements that
               appear within the immediately preceding pair of brackets or
               braces.  In the following example, you can select itemname and
               its delimiter zero or more times.  Each instance of itemname
               must be preceded by a comma:

               [,itemname] [ ...  ]

               If a punctuation character precedes the ellipsis, you must use
               that character as a delimiter to separate repeated elements.
               However, if you select only one element, the delimiter is not
               required.  In the following example, the comma should not
               precede the first instance of itemname:

               [itemname] [, ...  ]

...            Within examples, horizontal ellipsis indicate where portions of
               the example are omitted.

  How to install MPEX/3000, SECURITY/3000 and VEAUDIT/3000.

Please install the accompanying tape promptly, and return it to VESOFT.
The installation process makes no modifications to your operating system, and
does not require any special log on (OPERATOR.SYS is enough).

First-time installations do not interrupt system operations in any way;
subsequent updates require that none of our files are in use during the
installation.

1.  Mount the VESOFT tape, place it online and setup a FILE equation for your
    tape device LDEV class or number:
    :FILE VESOFT; DEV=TAPE  (or  DEV=CTAPE for cartridge, or  DEV=7, or...)
    :RESTORE *VESOFT; @.@.@; CREATE; SHOW
    Then =REPLY to the tape request, if necessary.

    This will restore all files and automatically create the required account
    structure.
    Please verify that all files have been restored before continuing.

2.  Existing users only:  Before continuing, check that no VESOFT products are
    currently in use.  The installation job will clearly warn you if any files
    are in use, but MPEX users can easily check this before starting by typing:
    %LISTF MAIN.PUB.VESOFT, ACCESS

3.  Launch the installation job by running our install program:
    :RUN VECREATE.PUB.SYS
    The job sends status messages to the system console as it executes.

-   The installation job installs our software into the VESOFT account, as well
    as creating the VECSL (VESOFT contributed software library) account.

-   We automatically install demonstration versions of any products that you
    are not licensed to use.  Please take advantage of this opportunity to try
    these other products.

-   The installation automatically updates any VESOFT segments that you have
    already installed in SL.PUB.SYS.  It does NOT modify SL.PUB.SYS if you
    haven't already manually installed our segments there.

-   For help on the new features in this version, refer to the printed manuals
    (new and modified features are identified in the table of contents), or use
    our online help facility:
    %HELP NEWS      or      %SEC HELP NEWS      or      %VEAUDIT HELP NEWS

Although the installation instructions are duplicated here, any printed
instructions included with your tape should be used in preference to these.


Introduction__4
Introduction

MPEX (MPE eXtended) is an extremely useful utility that improves the way you do
your system management, program development, and console operations tasks.

   * It lets you EXECUTE MPE COMMANDS (like :COPY, :COBOL, :RENAME, etc.) on
     FILESETS.  A single MPEX command can take the place of hundreds of MPE
     commands, saving you time and reducing the possibility of error.  Commands
     like :ABORTJOB, :BREAKJOB, etc.  are executed on USERSETS.

   * It lets you SELECT FILES by various attributes like disc space used, last
     access date, by file creator, etc.  -- something you just can't do without
     MPEX.

   * It implements entirely NEW COMMANDS like %ALTFILE that can do things no
     existing MPE command can do, such as alter a file limit, change file's
     creator ID, etc.  %EDIT command will execute several EDITOR commands on
     many files at once, and so on.

   * With its MPEX HOOK feature, MPEX lets you execute REDO, :RUNs, UDCs, and
     MPEX COMMANDS from within virtually any utility, such as EDITOR, QUERY,
     etc.  And more non-fileset-handling useful commands are available (FILTER,
     GOON, DEVCONTROL, ALARM, etc.) - see the Manual for details.

   * Finally, MPEX implements virtually all of the MPE/iX user interface
     features (variables, command files, implied :RUN, :CALC, :COPY, :PRINT,
     etc.) - even on MPE/V! Not only does this add a lot of power to your MPE/V
     system, but it also lets you use the same job streams on MPE/V and on
     MPE/iX (if you have both).  IMPORTANT:this feature lets you "live" in
     MPEX!

MPEX is not a replacement of or change to the existing operating system.  It is
a stand-alone program (just like EDITOR, QUERY, etc.).  To use MPEX (see also
Running MPEX in this manual), simply type:

   :RUN MAIN.PUB.VESOFT

You should see the MPEX product banner and version number, a hint, and then you
will be prompted with MPEX's "%" prompt; you can then type in any MPEX command
or MPE command (including :RUN, UDCs, etc.).  To get help on any command or
operation, type

   %HELP


MPEX__Self_demo_5
MPEX: Self demo
To see our "self-demo", just type

   %DEMO

and the fundamental MPEX features will be explained with working examples.

To exit MPEX, simply type "E", "END", "EXIT" or "QUIT".

Note: MPEX emulates the MPE/iX user interface, even on CLASSIC systems, so you
      can use these features on MPE/V as well as on MPE/iX.  Because many of
      our users may not be familiar with MPE/iX, we define all our
      MPE/iX-compatible features from scratch without requiring any prior
      MPE/iX knowledge.  However, even readers who are familiar with MPE/iX
      should still read those sections as we often go beyond the standard
      MPE/iX features.

POSIX note: As of MPE/iX version 4.5, POSIX compatibility has been added to the
            MPE operating system.  Where appropriate, POSIX notes such as this
            one will be included in the text pointing out differences between
            normal MPE/MPEX commands and commands enhanced for POSIX.  Examples
            showing a difference in syntax for POSIX are marked with (POSIX).


Examples_of_MPEX_commands__6
Examples of MPEX commands

An example is worth a thousand syntax diagrams.  Here are only a few of the
things you can do with MPEX.  We won't discuss each one in too great a detail
-- see the appropriate manual section for a complete explanation.  (Remember
also that these examples are only the tip of the iceberg; there are many more
features discussed further in the manual.)

SYSTEM MANAGEMENT


Examples__System_Management__7
Examples: System Management

%ALTFILE @.@(CREATOR="JOHN"); CREATOR=MANAGER

     After you purge the user JOHN, this command will change all of his files
     to have creator ID (IDentification) MANAGER.

%ALTFILE @.DATA-CUST@.DATA(INTCODE=0); FLIMIT=EOF*1.5

     Sets the file limit of the (MPE and KSAM) files in the DATA group (except
     for files that start with CUST) to be 50% greater than the current EOF.

%ALTSPOOLFILE $STDLIST.@.@(SPOOL.JSNAME="MCOMPILE"); PRI=8

     Changes to 8 the output priority of all $STDLISTs belonging to jobs that
     logged on with job/session name MCOMPILE.

%COPY @.@.AP, @/=.@.APBACKUP; KEEPATTR

     Copies all the files in the AP account into the APBACKUP account,
     preserving file attributes (e.g.  creator ID, file limit, lockword, etc.).

%COPY @.DATA, =.=; YES; DEV=ROBIN#

     Copies all the files in the group DATA (including IMAGE databases and KSAM
     files!) over a DSLINE (or NS LAN, etc.) to system ROBIN, purging any files
     that already exist with the same name.

%DELETESPOOLFILE $STDLIST.@.@(SPOOL.OUTPRI<=2)

     Deletes all the $STDLISTs that have output priority 2 or less.

%LISTF MYFILE, ACCESS

     Shows all the accessors of MYFILE: accessing program name, access job
     number/name, current record being accessed, etc.

%LISTF @.DATA, DISCUSE

     Shows which devices the files in the "DATA" group reside on (invaluable if
     you're interested in disc balancing).

%MPEXSTORE @.@.@ - @.@.SYS - @.@.VESOFT &
     (ACCDATE<TODAY-90 and NOT ISPRIV); *T; SHOW
%MPEXSTORE / - /SYS/ - @.@.VESOFT &
     (ACCDATE<TODAY-90 and NOT ISPRIV); *T; SHOW   (POSIX)

     Implements the sophisticated MPEX FILESETS (with multiple "-"s, combining
     MPE & HFS syntax, selection criteria, etc.) on the MPE :STORE command.

%REPEAT
%>ECHO -----Formatting !MPEXCURRENTFILE
%>RUN MYFMT;INFO="!MPEXCURRENTFILE"
%>FORFILES X@.SOURCE

     Performs a user-specified set of commands (here ECHO and RUN) on a
     fileset.

%SHOWOUT $STDLIST.@.@(SPOOL.OUTPRI=1)

     Shows information on all $STDLISTs with output priority 1 in the system,
     including job number, job name, ready date, etc.

%SHOWOUTJ COMP010,@.PROD

     Shows information on all the spool files created by a job that logged on
     with job name COMP010 in the PROD account.

MANAGING DISC SPACE


Examples__Managing_Disc_Space__8
Examples: Managing Disc Space

%ALTFILE @.@.@; XLTRIM; KEEPAMDATES  (MPE/iX)
%ALTFILE /    ; XLTRIM; KEEPAMDATES  (POSIX)

     On MPE/iX systems, this command releases a lot of currently unused disc
     space that has been allocated to files, without changing the capacity
     (FLIMIT) of the files in any way.  (The "KEEPAMDATES" option tells MPEX
     not to change the last access/modify dates of any files it alters, so they
     won't appear on your next partial backup.)

%COPY @.@.MFG, =.=.MFGBACK

     Makes a backup copy of the MFG account to the MFGBACK account.

%LISTF @.DATA(ISASCII and SAVABLESECTORS>100),2

     Lists all the MPE ("flat") files that have FLIMIT greater than EOF and/or
     inefficient R/B (blocking factor); by SQUEEZEing and reblocking (BEST)
     them one might save more than 100 sectors on each file.

%ALTFILE RPT@.DATA(ISASCII); SQUEEZE

     "Squeezes out" all the unused space between EOF and file limit in all
     blank-code files that start with RPT in the DATA group.

%EDIT @.SOURCE(CODE="EDTCT"), SET VARIABLE

     Converts all EDITOR COBOL-format files in the SOURCE group to be variable
     record length files, saving 30-50% of the disc space while still leaving
     them editable, compilable, etc.

%LISTF @.@.@(ACCDATE<TODAY-120), 3

     Finds all the files that haven't been accessed in the last 120 days and
     lists their names, access dates, modify dates, etc.; also shows total
     number of files and sectors.

%PURGE K#######.@.@+LOG####.@.@(CREDATE<TODAY-7)

     Purges EDITOR K-files and system log files created more than a week ago.
     Prompts you for confirmation before purging anything!

%PURGE @.@.@ - @.@.VESOFT(ACCDATE<TODAY-120 and NOT ISPRIV)
%PURGE / - @.@.VESOFT(ACCDATE<TODAY-120 and NOT ISPRIV)  (POSIX)

     Purges all the non-privileged (mostly non-IMAGE) files that haven't been
     accessed in the last 120 days.

PROGRAM DEVELOPMENT


Examples__Program_Development__9
Examples: Program Development

%COBOL AP@.SOURCE,AP@.PUB,*LP

     Compiles using COBOL and :PREPs all the AP@.SOURCE files into program
     files with the same name in the PUB group.  (Of course, the same works for
     FORTRAN, PASCAL, RPG, etc.)

%PRINT @.SOURCE;SEARCH="ITEM-NUM" or "ITEM-NAME" or "ITEM-DESC";NUM

     Finds all the occurrences of the strings "ITEM-NUM" or "ITEM-NAME" or
     "ITEM-DESC" in all files in the SOURCE group.  (Does your editor give you
     this kind of power?)

%PRINT @.SOURCE;SEARCH=DELIM "MYVAR";PREV="PROCEDURE" or "FUNCTION"

     Prints all occurrences of the string "MYVAR" -- for each occurrence, also
     prints the last prior occurrence of the line that contains the strings
     "PROCEDURE" or "FUNCTION"; in other words, shows you all the lines that
     refer to "MYVAR" AND indicates what procedure they occur in!

     The DELIM means that "MYVAR" will be searched for as a delimited string,
     i.e.  surrounded by special characters (e.g.  lines containing "TEMPMYVAR"
     or "MYVARIATION" will not be found).

%COBOL @.PRODSRC(FSEARCHEXP("'CUST-NO' or 'CUST-NAME'")>0), =.PUB

     Recompiles all the files in PRODSRC that contain within them either the
     string CUST-NO or the string CUST-NAME!

%EDITCHG @.SOURCE, "ITEM-NO", "ITEM-NUMBER"

     Changes all occurrences of "ITEM-NO" to "ITEM-NUMBER" in all files in the
     SOURCE group, /KEEPing only those files that were actually changed.

%LISTF @.PRODSRC(MODDATE>3/15/91), 3

     Finds all the files in PRODSRC that have been modified since 3/15/91
     (perhaps the last production release date).

%PRINT @.SOURCE; OUT=*LP; PAGEHEAD; NUM

     Prints all the SOURCE group files to the line printer (with page headers,
     nicely-formatted line numbers, etc.).

%COBOL @.PRODSRC(MODDATETIME>VEFINFO(FILE+".PUB").MODDATETIME), =.PUB

     Compiles all the PRODSRC files whose modify dates (and times) are later
     than the modify dates (and times) of files with the same name in the PUB
     group (VEFINFO(FILE+".PUB").MODDATETIME).  In other words, this recompiles
     all the programs that have been modified but not recompiled into PUB.
     Fancy, eh?

DATABASE MANAGEMENT


Examples__Database_Management__10
Examples: Database Management

%ALTFILE CUST?#.DB(DBSETTYPE="D"); DEV=2
%ALTFILE CUST?#.DB(DBSETTYPE<>"D"); DEV=3

     These two commands move all detail datasets of the CUST database to device
     2 and all non-detail datasets to device 3.

%ALTFILE @.@.AP(CREATOR<>"DBA" and ISPRIV); CREATOR=DBA

     Changes the creator ID of all AP databases (ISPRIV) to be DBA, thus making
     sure that DBA -- and only DBA -- can run DBUTIL, DBSTORE, etc.  against
     all those databases.

%COPY APDB@, DBNEW@; DEV=3

     Copies the APDB database into a new database called DBNEW, moving all the
     files onto disc device 3.

%DBADGALT @.DB(DBSETFULLNESS>.8 and MODDATE>TODAY-30), 0.6
%DBGENALT @.DB(DBSETFULLNESS>.8 and MODDATE>TODAY-30), 0.6
%DBMGRALT @.DB(DBSETFULLNESS>.8 and MODDATE>TODAY-30), 0.6

     Use ADAGER, DBGENERAL/BRADMARK, or DBMGR/DISC to alter the capacity of all
     datasets in the DB group that are currently more than 80% full (and have
     been modified within the last 30 days) so that they will only be 60% full.

%LISTF @.@.AP(DBSETFULLNESS>.70 and MODDATE>TODAY-7), DB

     Shows database information (dataset name, type, capacity, etc.) for all
     datasets in the AP account that are more than 70% full and have been
     modified in the past week.

%RENAME MYDB@(ISPRIV), NEWDB@

     Renames a database.

FILE SYSTEM SECURITY


Examples__File_System_Security__11
Examples: File System Security

%LISTF @.@.@(ISPROG and PROG.PMCAP), 5

     Finds all the privileged-mode program files in the system and lists their
     program file information.

%LISTF @.@.PAYROLL(ACCDATE>=TODAY-2)

     On Monday, this shows all files in the PAYROLL account that were accessed
     over the weekend.

%SECURE @.@.@(ISPROG and ISRELEASED and DIRGROUP.CAP("PM"))

     Secures all the :RELEASEd program files in privileged groups (which are a
     SERIOUS THREAT to system security).

%LISTF @,SEC

     Shows the "true" access to the file, factoring in both the group- and
     account-level restrictions as well as the file restrictions and the
     :RELEASE/:SECURE status.

JOB STREAM PROGRAMMING


Examples__Job_Stream_Programming__12
Examples: Job Stream Programming

!JOB JOBA,MGR.PROD
!RUN MAIN.PUB.VESOFT;PARM=1
%WHILE JSCOUNT("JOBB,MGR.PROD&BATCH")>0 DO
%  PAUSE 120
%ENDWHILE
%EXIT
...

     If the job JOBB,MGR.PROD is logged on, waits until it logs off before
     continuing execution of JOBA.

!JOB JOBA,MGR.PROD
...
!RUN MAIN.PUB.VESOFT;PARM=1
%WHILE VEFINFO("DATAFILE").OPENED DO
%  PAUSE 120
%ENDWHILE
%EXIT
...

     If the file DATAFILE is opened, waits until it is closed before continuing
     execution.


PRINTOPREPLY_13
PRINTOPREPLY

!JOB JOBA,MGR.PROD
...
!RUN MAIN.PUB.VESOFT;PARM=1
%SETVAR FNAME PRINTOPREPLY('Which file should we output to?')
%IF FEXISTS(FNAME) THEN
%  IF PRINTOPREPLY('OK to purge file '+FNAME+'?')='Y' THEN
%    PURGE !FNAME
%  ENDIF
%ENDIF
%FILE MYOUTFIL=!FNAME,NEW;SAVE
%EXIT
...

     Asks the console operator for feedback via the :REPLY command and uses it
     to set up a :FILE-equation and possibly purge the file (if it already
     exists).


Running_MPEX__14
Running MPEX

There are several ways in which you can run MPEX:

   * Interactively, by saying

        :RUN MAIN.PUB.VESOFT

   * In BATCH, by saying

        !JOB MYJOB,USER.ACCOUNT
        !RUN MAIN.PUB.VESOFT;PARM=1
        %mpex commands...

   * With an INFO= string containing a single MPEX command that is to be
     executed:

        :RUN MAIN.PUB.VESOFT;INFO="LISTF @.@.AP,DB;*LP"

   * Using the "MPEX HOOK" from within a program such as EDITOR, QUERY, etc.:

        :RUN EDITOR.PUB.VESOFT;LIB=P
        /TEXT MYFILE
        ...
        /%COBOL MYFILE,MYPROG
        << MPEX executes the %-prefixed command >>

All of these ways of running MPEX are subject to the following features:

   * You may specify commands that are to be executed every time a user enters
     MPEX.  This may be done on the system level, the account level, the group
     level, or a combination of all three.

   * You may (if your system manager allows this) tell MPEX not to recognize
     UDCs -- this will substantially speed up entry into MPEX.

RUNNING MPEX INTERACTIVELY


Running_MPEX_interactively__15
Running MPEX interactively

If you just say

   :RUN MAIN.PUB.VESOFT

you'll enter MPEX's interactive mode (MPEX will prompt you with a "%").

In fact, many of our users like to "live" in MPEX -- they just run MPEX when
they log on (they might even have an OPTION LOGON UDC to do this) and don't get
out until they're ready to do %BYE.  This can be very useful because

   * Virtually every MPE command can be executed from within MPEX (so you
     almost never need to exit into the Command Interpreter).

   * MPEX's command history facility (%REDO, %LISTREDO, and %DO) is so useful
     that you might want to always have it available.  With the MPEX HOOK, we
     make our powerful %REDO available in virtually every program (EDITOR,
     QUERY, etc.) -- about the only place that still doesn't have it is the
     ordinary MPE/V Command Interpreter.

   * MPEX is a very powerful process-handling environment, with which you can
     manage multiple suspended processes, quickly pop into and out of programs,
     and so on.

(Alternatively, you might get all these features by "living" in the HOOKed
EDITOR [or QUERY or whatever], in which you'll also have the command history
and the full power of MPEX commands.)

RUNNING MPEX IN BATCH


Running_MPEX_in_batch__16
Running MPEX in batch


MPEX_batch_job_aborts_17
MPEX batch job aborts

If you :RUN MAIN.PUB.VESOFT in batch, MPEX will (just like MPE) abort after the
first error (unless you do a %CONTINUE before the error).

What constitutes an error?
   * Any MPE command that gets a CIERROR.
   * Any program run that aborts (or actually any time a program terminates
     with the JCW set to FATAL).
   * A fatal error on an MPEX command.

Not all MPEX commands that get an error cause a job stream to abort.  What if
you do a fileset %COBOL compile and one of a hundred compiles fails? Is that an
error because one compile failed, or a successful result because 99 compiles
completed OK?

At the moment we don't treat this as an error, but we're considering changing
it (if we decided that we need to for greater MPE compatibility).  Keep this in
mind -- if you want the job to continue even though an error might occur in a
particular command, always put a CONTINUE in front of the command JUST IN CASE.


HPAUTOCONTTOPLEVEL_18
HPAUTOCONTTOPLEVEL
What if you always want the job to continue, even if an error occurs in any of
the commands.  If you say

   %SETVAR HPAUTOCONTTOPLEVEL TRUE

then MPEX will enter "auto-:CONTINUE" mode, in which command errors will NEVER
cause the entire MPEX run to abort.  To change back to default mode, say

   %SETVAR HPAUTOCONTTOPLEVEL FALSE

Note that if you run MPEX in batch and want to give MPEX commands that start
with "!", e.g.

   !JOB ...
   !RUN MAIN.PUB.VESOFT;PARM=1
   %!LISTF @.@.@(ACCDATE<TODAY-120),3
   ...

you must prefix the MPEX command with either a "%" (as we do here) or with a
space -- if the "!" is put in the first column, MPE automatically replaces it
with a ":" behind our backs.  Commands that you don't prefix with a "!" need
not have a leading space or "%"; however, it's probably a good idea to always
prefix MPEX commands in your job streams with a "%" -- it'll make it clear to
anybody who's reading the stream that this is an MPEX command.


MPEXCONTINUECOLON_19
MPEXCONTINUECOLON
When you say

   :ABC &
   :DEF GHI

in a job stream, MPE executes the command as "ABC DEF GHI" -- even though the
job stream does contain a leading ":" at the start of the "DEF GHI" line (or
perhaps a leading "!"), it gets stripped out when the two lines are merged
together.

If you said

   :ABC &
   :DEF GHI

in older versions of MPEX, MPEX would NOT strip out the colon; instead, it
would execute the command as ":ABC :DEF GHI".

For the sake of compatibility with these older versions, MPEX leaves the
continuation line's colon in; however, if you set the JCW MPEXCONTINUECOLON to
1, MPEX will instead do the same thing as MPE does (i.e.  strip out the leading
colon in the continuation line).  We wish that we could make this the normal
behavior, but we feel that we need to remain compatible with older versions of
MPEX, especially in situations which might happen in production job streams.

When you run CI.PUB.VESOFT, the leading colons in continuation lines will
always be stripped out (just like in MPE).  This is because CI.PUB.VESOFT is
intended to be as compatible as possible with MPE.

RUNNING MPEX WITH ;INFO=


Running_MPEX_with__INFO___20
Running MPEX with ;INFO=


INFO__21
INFO=

If you say

   :RUN MAIN.PUB.VESOFT;INFO="command"

MPEX will execute the command and return to MPE.  This is the "immediate" mode,
used when you want to execute just one specific MPEX command (often from a UDC
or a command file).

The only special things you need to know about immediate mode are:

   * MPEX won't output the header before executing the command.

   * If you want to speed up this operation (perhaps by turning off UDCs
     initialization, which takes MPEX several seconds and may not be needed if
     you know exactly what command you're executing), see the Speeding Up MPEX
     Start-up section below.

SPECIFYING COMMANDS TO BE EXECUTED EACH TIME MPEX IS ENTERED


Specifying_commands_to_be_executed_when_MPEX_is_entered__22
Specifying commands to be executed when MPEX is entered


MPEXMGR_files_23
MPEXMGR files

MPE's OPTION LOGON UDCs let you indicate commands to be executed every time you
log on -- MPEX also has a mechanism for specifying commands to be executed
every time MPEX is entered.

When you enter MPEX, the first thing it does is execute the command file
MPEXMGR.PUB.VESOFT.  For instance, if MPEXMGR.PUB.VESOFT contained the lines

   INITUDCS
   SETVAR MPEXPROMPT "MPEX> "
   SET CAPABILITY,PURGE,AM
   SET DEFAULT,PURGE,?

then these lines would be executed every time any user enters MPEX.  UDCs would
be initialized (INITUDCS), the MPEX prompt would be changed (SETVAR
MPEXPROMPT), and the PURGE command would be additionally secured (SET
CAPABILITY & SET DEFAULT).

The MPEXMGR.PUB.VESOFT file might contain, for example,

   UNLESSFAST CALC READHINT('MPEXHINT.HELP.VESOFT')
   INITUDCS
   UNLESSFAST INITMPEXMGR
   INITREDO

What does this mean?


Hints_24
Hints
   * The UNLESSFAST CALC READHINT('MPEXHINT.HELP.VESOFT') prints a random
     "hint" -- one- or two-line message about a feature of MPEX that you may or
     may not be familiar with (this is done essentially for educational
     purposes).  The "UNLESSFAST" means that the hint should not be printed if
     you're using the fast MPEX start-up option (see below).

   * The INITUDCS command is documented above.  It makes MPE UDCs accessible
     from MPEX.


_INITMPEXMGR_25
%INITMPEXMGR
   * "UNLESSFAST INITMPEXMGR" says that MPEX should execute the "INITMPEXMGR"
     command unless the fast MPEX start-up option (which will be explained
     shortly) has been selected.

     An INITMPEXMGR command tells MPEX to execute the contents of the
     MPEXMGR.PUB file in your logon account and the MPEXMGR file in your logon
     group.  If one or both of those files doesn't exist, no problem; however,
     if they do, they'll be executed just like the MPEXMGR.PUB.VESOFT file is.

     Notice that commands you put before the INITMPEXMGR command can be
     "overridden" by commands in a user's own MPEXMGR file(s).  The exception
     is "SET CAPABILITY" commands, which CANNOT be removed by users at all (see
     "%SET CAPABILITY" in this manual).  For similar reasons, you should place
     any commands that MUST be executed prior to the INITMPEXMGR command.  If a
     user's own MPEXMGR file contains an error, processing of the MPEXMGR
     file(s) will stop at that point.

     Again, the reason that MPEX doesn't automatically execute the MPEXMGR and
     MPEXMGR.PUB files is for speed of start-up -- by having MPEXMGR and
     MPEXMGR.PUB execution controlled from the MPEXMGR.PUB.VESOFT file, we let
     you omit it entirely or put an "UNLESSFAST" in front of it.


_INITREDO_26
%INITREDO
   * INITREDO is not documented elsewhere, since it is only really useful in
     the MPEXMGR.PUB.VESOFT file.  INITREDO simply initializes MPEX's %REDO,
     %DO, and %LISTREDO command handling structures.

     The only reason that MPEX doesn't automatically do this (but rather
     requires an MPEXMGR command to do it) is that this may take some time, and
     we want to allow you to make this step (REDO initialization) optional.

     See "SPEEDING UP MPEX START-UP" below.

Other useful commands you might want to include into the MPEXMGR.PUB.VESOFT
file include:

   * %SET CAPABILITY commands to restrict access to certain MPEX commands, e.g.

     %SET CAPABILITY,PURGE,AM

   * %SET DEFAULT commands to change the default mode of execution for MPEX
     commands, e.g.

     %SET DEFAULT,PURGE,?

     to make sure that (by default) all purges will ask for yes/no
     verification.

   * %SET DATE commands to change the input format for MPEX dates; our European
     customers like to say

     %SET DATE,DMY

   * Various :SETJCW commands to control the behavior of MPEX's REDO command
     history (see "%REDO Facility Options" in the %REDO chapter).

   * The command

     %WAKEUP.PUB.VESOFT

     which lets you use the [BREAK] key to abort not your entire process tree
     but only a particular process (see "MPEX Process Handling" in the MPEX
     Special Topics chapter).

Your MPEXMGR.PUB and MPEXMGR.logongroup files are also executed at MPEX entry
time, but after the MPEXMGR.PUB.VESOFT file.  (Note: you do not need Read
access to the MPEXMGR files, only execute).  Therefore:

   * If your MPEXMGR.PUB.VESOFT file already has an %INITUDCS command and an
     %INITREDO command, there's no reason to put them into your own MPEXMGR
     files -- the UDCs and the redo facility are already initialized;
     reinitializing them would just waste time.  (In fact, under certain
     circumstances, it might actually give you some unpleasant error messages!)

   * Never put an %INITMPEXMGR command into your MPEXMGR.PUB or
     MPEXMGR.logongroup file.  "%INITMPEXMGR" is essentially the same as "%XEQ
     MPEXMGR.PUB" and "%XEQ MPEXMGR.logongroup"; if you put it into one of
     those files, it'll loop and eventually cause a stack overflow.

   * In general, therefore, you should not try to copy the default
     MPEXMGR.PUB.VESOFT into your own group or PUB group, since the commands
     that MPEXMGR.PUB.VESOFT usually contains -- %INITMPEXMGR, %INITREDO, and
     %INITUDCS -- are not appropriate in your own MPEXMGR files.

Other commands, though -- %SETs, %RUN WAKEUP.PUB.VESOFT, etc.  -- can certainly
be put into your MPEXMGR.PUB and MPEXMGR.logongroup files.  Remember that, in
general, MPEXMGR.PUB.VESOFT, MPEXMGR.PUB, and MPEXMGR.logongroup can contain
any MPEX commands.

IMPORTANT SECURITY CONSIDERATIONS FOR THE MPEXMGR FILE


Important_security_considerations_for_the_MPEXMGR_file_27
Important security considerations for the MPEXMGR file

As noted above, the MPEXMGR file is a great place to put %SET CAPABILITY
commands.  However, anyone who has WRITE access to an "MPEXMGR" file could
conceivably change it to do something other than intended, such as removing
those %SET CAPABILITY commands that you put in the file.  While the
MPEXMGR.PUB.VESOFT file should remain secure if the group and account
attributes we set up during installation are not changed, your account level
MPEXMGR files might not be so safe.

For similar reasons, you should place any critical commands PRIOR to any
INITMPEXMGR command.  Since INITMPEXMGR will execute the files MPEXMGR.PUB and
MPEXMGR in the user's account and group respectively, any commands that a user
places in these files may be executed BEFORE the appropriate %SET CAPABILITY
command(s) in MPEXMGR.PUB.VESOFT.  Also, careless or intentional mistakes in
these files can stop the entire MPEXMGR start-up sequence, leaving the system
unprotected from the user.

One last thing to be aware of, although not specifically related to security,
is that any commands that appear AFTER the INITMPEXMGR command in
MPEXMGR.PUB.VESOFT may override commands and settings in the user's own MPEXMGR
file.  Sometimes this is desired, but often it is not.  So if some items should
have a default, but individual users may be allowed to change that default
(such as the HPPATH or MPEXPROMPT variables), defaults should be placed BEFORE
the INITMPEXMGR command.

SPEEDING UP MPEX START-UP


Speeding_up_MPEX_start_up__28
Speeding up MPEX start-up

Like so many good things, some of what MPEX does at start-up -- before you type
in your first command -- takes time.  As a rule, MPEX must:

   * Figure out what MPE UDCs you have set up; this includes

       - FOPENing COMMAND.PUB.SYS;

       - Finding three directory entries to determine what UDC files you have
         set;

       - Reading several COMMAND.PUB.SYS records to figure out all your UDC
         filenames;

       - FCLOSEing COMMAND.PUB.SYS;

       - FOPENing every one of those UDC files;

       - Reading each UDC file to determine what UDC commands it contains (and
         record their names and record numbers);

     (The CI has to do all the above when you log on -- this is why logons can
     sometimes take a while.  We have to do this again since the CI's UDC
     tables are inaccessible to us.)

   * Open your REDO command history file.

   * Open your MPEXMGR.PUB and MPEXMGR files, and execute all the commands kept
     in each of them.  (Even if you don't have these files, the FOPEN attempts
     take time.)

   * And many other things that can't be avoided in any case.

MPEXMGR.PUB.VESOFT command file -- which is executed whenever you enter MPEX --
lets you control which of the above operations are done and which are not.
What's more, it lets you have two modes of operation (which you can select at
:RUN MAIN.PUB.VESOFT time) --

   * A normal mode, which gives you the full power of UDCs, the REDO command
     history, and MPEXMGR files.

   * A fast-start mode, which doesn't support some or all of the above, but is
     faster at start-up time.  To enter it, you say


PARM_1_29
PARM=1

        :RUN MAIN.PUB.VESOFT;PARM=1

     The ;PARM=1 indicates fast-start mode.

     If you have no control over how MPEX.PUB.VESOFT will be run (e.g.  if
     you're using the MPEX HOOK facility, which runs MPEX for you), you can
     trigger fast-start mode by saying


MPEXFASTSTART_30
MPEXFASTSTART

        :SETJCW MPEXFASTSTART=1

     before MPEX is run.  (Remember that this will apply to all subsequent runs
     of MPEX in your session until you say :SETJCW MPEXFASTSTART=0.)


_UNLESSFAST_31
%UNLESSFAST
For instance, say that your MPEXMGR.PUB.VESOFT file says the following:

   UNLESSFAST :CALC READHINT('MPEXHINT.HELP.VESOFT')
   UNLESSFAST :INITUDCS
   UNLESSFAST INITMPEXMGR
   :INITREDO

What does this mean?

   * The random "hint" -- one- or two-line description of some MPEX feature
     that we want to make sure you know about -- is output unless you are in
     fast-start mode.

   * UDCs are to be initialized unless you are in fast-start mode.  UDC
     initialization is the most time-consuming of all the start-up tasks.

   * MPEXMGR.PUB and MPEXMGR.yourgroup files are to be executed unless you are
     in fast-start mode.

   * The REDO command history will always be initialized (even in fast-start
     mode).  We recommend this since the initialization is so quick (just one
     FOPEN) and the command history is so useful.

(The ":"s were also put in front of INITREDO and INITUDCS [which are, of
course, not MPE commands] for speed reasons -- using them prevents MPEX from
trying to interpret them as "true" MPEX commands, which would take a couple
more disc I/Os.  It's complicated -- just trust us.)

The default MPEXMGR.PUB.VESOFT file that we give you says

 IF HPINTERACTIVE THEN
   INITREDO
   CONTINUE
   NOMSG UNLESSFAST :CALC READHINT('MPEXHINT.HELP.VESOFT')
 ENDIF
 INITUDCS
 UNLESSFAST INITMPEXMGR

We don't put an "UNLESSFAST" before the ":INITUDCS" for security reasons --
some people like to use UDCs to block out MPE commands (such as :SHOWCATALOG),
and we don't want to give everybody an easy way (running MPEX in fast-start
mode) to avoid this restriction.

If, however, you have no security problems with allowing people to avoid UDCs,
we suggest that you put an UNLESSFAST in front of the :INITUDCS.  This will
make it easy for people to get into MPEX very quickly (if they need to).

Let us point out, though, that the time it takes to get into MPEX isn't so long
at all, and the UDC support, REDO command history, and MPEXMGR features are
actually quite valuable.

We envision people using the fast-start option only in selected cases where
they want to do one thing with MPEX and want to do it very quickly.  For
instance, if you have a UDC from which you want to run MPEX with an INFO=
string to execute a specific MPEX command, you might want to use ;PARM=1
because you know that you won't be needing UDCs, REDO, or local MPEXMGR files.

CI.PUB.VESOFT (FOR MPE/iX EMULATION)


CI_PUB_SYS_32
CI.PUB.SYS


CI_PUB_VESOFT__33
CI.PUB.VESOFT
In MPE/iX, the command interpreter is available as a separate program called
CI.PUB.SYS.  You can, for instance, say

   :CI.PUB.SYS

and thus create a son CI process underneath your normal CI.  An :EXIT will
return you from the son CI to the father CI.

The most common use for this is when you want to run the CI with ;STDIN= or
;STDLIST= redirection:

   :FILE MYFILE,NEW;SAVE
   :RUN CI.PUB.SYS;INFO="SHOWOUT";PARM=3;STDLIST=*MYFILE

will make the CI do a SHOWOUT with output to the ;STDLIST= file.  The ;INFO=
string is the command to be executed; the ;PARM= contains some flag settings
we'll discuss shortly.

MPEX allows you to do something quite similar.  At installation time, the MPEX
program file is copied into the file CI.PUB.VESOFT -- when you run this
program, MPEX will try to emulate (even more closely than it normally does) the
behavior of MPE/iX's CI.PUB.SYS.  In particular:

   * The prompt will default to a ":" (rather than a "%"); to change the
     prompt, you should set the variable HPPROMPT (not MPEXPROMPT).

   * All commands entered into CI.PUB.VESOFT will be executed as MPE or MPE/iX
     commands, not as MPEX fileset handling commands.  (This is the same
     behavior as if you had RUN MAIN.PUB.VESOFT and prefixed each command you
     typed with a ":".) The new MPE/iX commands (like :COPY, :PRINT, :INPUT,
     etc.) will still be available, but without fileset handling.


Debugging_MPEX_command_files_UDCs__HPCMDTRACE_JCW__34
Debugging MPEX command files/UDCs: HPCMDTRACE JCW
   * Instead of looking at the MPEXCMDTRACE variable (to see if command tracing
     should be on), CI.PUB.VESOFT looks at the HPCMDTRACE variable.


CIMGR_files_35
CIMGR files


_INITMPEXMGR_36
%INITMPEXMGR

   * Instead of executing MPEXMGR.PUB.VESOFT, CI.PUB.VESOFT executes
     CIMGR.PUB.VESOFT.  If CIMGR.PUB.VESOFT has an INITMPEXMGR command, it
     executes CIMGR.PUB.logonaccount and CIMGR.logongroup.logonaccount.

   * If CI.PUB.VESOFT is run with:

       - ;PARM=0 then the CI header message will be displayed, the ;INFO=
         command (if any) will be executed, and the CI process will continue
         prompting for input until you type :EXIT.

       - ;PARM=1 then the CI header message will be displayed, the ;INFO=
         command will be executed, and the CI process will TERMINATE.

       - ;PARM=2 then the CI header message will not be displayed, the ;INFO=
         command (if any) will be executed, and the CI process will continue
         prompting for input until you type :EXIT.

       - ;PARM=3 then the CI header message will not be displayed, the ;INFO=
         command will be executed, and the CI process will TERMINATE.

As we said, this should emulate the behavior of MPE/iX even more closely than
MPEX normally does; however, MPEX fileset handling commands will not be
available from this mode.

CHANGING THE MPEX PROMPT


Changing_the_MPEX_prompt__37
Changing the MPEX prompt

One of the things that MPEX lets you do is change the MPEX prompt from its
default value of "%".  By setting the MPEX variable MPEXPROMPT, e.g.

   %SETVAR MPEXPROMPT "Yes, boss? "

you can set the prompt to whatever you please.  For instance, you might say

   %SETVAR MPEXPROMPT "!!HPCMDNUM/!!HPUSER/!!HPTIMEF %"

then MPEX will prompt you with something like:

   182/EUGENE/10:15 AM %

Now, whenever you look at the prompt, you'll see the current command number
(useful for future %REDOs), your user name (good for reminding you which
computer or logon you are using if you connect to multiple CPUs), and the
current time of day.

As you see, the MPEXPROMPT may include MPEX variables that are substituted for
when the prompt is printed.  HPCMDNUM and HPTIMEF are common examples of what
people might put into their prompts, but you can actually include any variable
or constant you want.

Note that we use two "!" characters in this particular %SETVAR command.  This
is because when MPEX sees the "!" character, it tries to evaluate the variable
before executing the command, so your MPEXPROMPT will not be dynamically
evaluated.  Seeing two "!" characters in the command, MPEX translates this into
a single "!" character in your prompt variable which causes MPEX to evaluate it
AGAIN when displaying your prompt.  See the A Few Comments About The "!"
Character section of the MPEX VARIABLES chapter.

Running under MPE/iX


MPEX_and_MPE_iX__38
MPEX and MPE/iX

MPE/iX (formerly known as MPE/XL) is the version of the MPE operating system
created for the HP3000 series 9xx (aka SPECTRUM, RISC, HPPA or PA-RISC)
systems.  While the MPE/iX Command Interpreter (the "CI") provides a number of
enhancements to the old MPE/V CI, it still does not address any of the
fundamental improvements MPEX has made available to HP3000 users for many
years, helping them save time and improving the reliability of their work.  At
the time of this writing (1997), more than 5000 MPE/iX sites are using MPEX.

MPEX eXtends MPE/iX in several ways:

* MPEX lets you execute MPE commands -- like :COPY, :COB85XLK, :RENAME, :PURGE,
  etc.  -- on entire filesets (including temporary filesets, IMAGE db filesets,
  and -- for commands like :ALTSPOOLFILE, :DELETESPOOLFILE, etc.  -- on spool
  filesets)!

  MPEX also lets you execute MPE job-handling commands -- like :ABORTJOB,
  :BREAKJOB, :RESUMEJOB, etc.  -- on entire jobsets.

* MPEX's selection conditions allow you to:

  - select files by hundreds of different attributes such as "disc space used",
    "last access date", "file creator", etc.;

  - select program files by attributes like "has PM capability", "number of
    code segments", "is OCTCOMPed", etc.;

  - select database files by attributes like "dbset name", "dbset fullness",
    "dbset block wastage", etc.;

  - select spoolfiles by attributes like "state (active, ready, opened,
    locked)", "job number", "job aborted", etc.;

  - select jobs by attributes like "jobname", "intro time", "state (EXEC, SUSP,
    WAIT, INIT, SCHED)", etc.

* MPEX implements entirely new commands that do things no existing MPE/iX (or
  MPE/V) command does; for example,

  - %ALTFILE (which lets you change attributes of files, and gives you the
    ;XLTRIM disc-space-saving option);

  - %CHLOGON (which lets you switch to another logon without doing a :HELLO).

  - %PAUSEJOB (which suspends jobs until a future time or condition).

  It also implements new control structures like

  - %REPEAT...%FORFILES (which lets you execute arbitrary commands against MPEX
    filesets).

* MPEX HOOK gives you:

  - a REDO facility that lets you redo up to the last 1000 (or more) commands
    that you've typed into EDITOR, TDP -- virtually any program;

  - the ability to save files across account boundaries (if you have SM
    capability);

  - the ability to execute any MPEX command directly within HOOKed utilities.

* MPEX greatly enhances the MPE/iX user interface by providing:

  - new functions and variables, including hundreds of file attribute variables
    and functions; integer, boolean, string, real, date, and time functions;
    file and database I/O functions; special MPE access functions; terminal
    manipulation functions; and security-related functions (see Appendix for
    details); and

  - enhancements to existing commands, like %PRINT;SEARCH= (to search for text
    within filesets), new %LISTF modes (and the ability to create your own),
    and %COPY (which allows you to copy IMAGE databases, copy files across NS,
    etc.).

(CHG)  ENTERING MPE COMMANDS IN MPEX (':' and 'MPE' PREFIXES)


MPE_commands__39
MPE commands


__prefix_40
: prefix


MPE_41
MPE

Syntax:   %[:] command or UDC [command parameter(s)...]
          %MPE command or UDC [command parameter(s)...]

Examples: %PURGE @.DATA(ACCDATE<TODAY-120 and NOT ISPRIV)
          %:FILE X;REC=-80,,F,ASCII;NOCCTL;SAVE
          %MYPROG;PARM=123;MAXDATA=30000;LIB=G
          %S J                 << where S is a valid UDC >>
          %MPE LISTF MYFILE,3

MPE commands can be executed from within MPEX by just typing them.  Even though
most MPEX commands have the same name as their corresponding MPE command, they
are still being interpreted and executed by MPEX; you can speed up some of
these commands by prefixing them with a ":" or the word "MPE".

Also, most MPEX commands are upwardly-compatible with MPE in that MPEX
implements some EXTRA features while supporting the normal MPE syntax, however,
some commands are not upwardly-compatible with MPE -- for instance, the second
parameter in the %COBOL command is the program filename, not the USL file name.
(This way seemed more convenient, but if we had to do it over again, we'd have
called the command %COBOLPREP to make everything perfectly compatible.) If you
run into one of these incompatible commands and want to execute the MPE version
of it rather than the MPEX version, you can either type a leading ":" like
this:

   %:COBOL MYSOURCE,MYUSL

or preface the entire command with "mpe" like this:

   %MPE COBOL MYSOURCE,MYUSL

The difference between these two forms is that the colon prefix indicates to
MPEX that the command does not contain a fileset (you will get an error if you
supply one), and the "MPE" prefix causes MPEX to pass the command directly to
the COMMAND intrinsic.

For example, prefacing a %PRINT command with a ":" will speed up the execution
of the command (since MPEX does not have to do any fileset processing) while
still allowing the use of our extensions to the :PRINT command (such as
;SEARCH= or ;FORMAT=).  However, prefacing a %PRINT command with "mpe" will
generate an error if you try to use any extended feature of the %PRINT command.
(In fact, "%MPE PRINT" will fail on a CLASSIC system since there is no such
MPE/V command).

YES/NO PROMPTING ('?' PREFIX)


Yes_No_prompting__42
Yes/No prompting


__prefix_43
? prefix

Syntax:   %?command

Examples: %?PURGE @.DATA(ACCDATE<TODAY-120 and NOT ISPRIV)
          OK to process ABACUS.DATA (y/n)? Y
          -----Purging ABACUS.DATA
          OK to process ABIGAIL.DATA (y/n)? N
          OK to process ABRACADA.DATA (y/n)?  << return is pressed >>
          OK to process BANANA.DATA (y/n)? Y
          -----Purging BANANA.DATA
          ...

If you prefix an MPEX fileset-handling command with a "?", MPEX will prompt you
with

   OK to process <filename> (y/n)?

If you type N or press [RETURN], the file will be skipped.  Only if you type Y
will the command be executed against the file.

This can be very useful if you know you want to do something to a somewhat
ill-defined set of files (not something that can be exactly specified with +
filesets, - filesets, and selection conditions).  You could specify a fileset
that contains all the files you want to work on, and then just type N when
prompted for any of the files you don't want.

Naturally, this can also be particularly good for commands such as %PURGE, in
which you want to be doubly sure before going ahead with the operation.  This
is why many of our users add to their MPEXMGR.PUB.VESOFT file (see "Specifying
Commands To Be Executed Each Time MPEX Is Entered" in the Running MPEX section
of this manual).

   %SET DEFAULT,PURGE,?

This means that whenever somebody types

   %PURGE ...

MPEX will act as if he had typed

   %?PURGE ...


__prefix_44
! prefix
If he doesn't want yes/no prompting, he'll have to explicitly specify this by
saying

   %!PURGE ...

The "!" says "execute this in standard on-line mode", as opposed to "?" (with
yes/no verification) or "$" (in batch -- see below).

BATCH EXECUTION ('$' PREFIX)


Batch_execution__45
Batch execution


__prefix_46
$ prefix

Syntax:   %$command

Examples: %$COBOL AP@.SOURCE,AP@.PUB
          %$DELETESPOOLFILE $STDLIST.@.@(SPOOL.OUTPRI<=3)
          %$RUN MYPROG;LIB=G;PARM=100

Whenever you prefix a command (an MPE command or an MPEX command) with a "$",
that command will be executed OFFLINE, in a specially created job stream with
the following characteristics:


MPEXDEFAULTJOBNAME_47
MPEXDEFAULTJOBNAME
   * It will log on with a job name equal to the first 8 characters of the
     command you typed.  This can be overridden by setting the variable
     MPEXDEFAULTJOBNAME to a specific job name.

   * The job stream will log on with the same user, account, and group names
     that you logged on with.


MPEXDEFAULTJOBPARMS_48
MPEXDEFAULTJOBPARMS
   * It will log on with job parameters ";OUTCLASS=,1" -- thus the $STDLIST
     will go to the spooler but will not print since it will be deferred.  You
     can alter this using the SUBMIT command or by setting the variable
     MPEXDEFAULTJOBPARMS to the desired default job parameters, e.g.

        %SETVAR MPEXDEFAULTJOBPARMS "OUTCLASS=,2;PRI=ES"

     For instance, if you're logged on as "JANE.AP,DEV" and you execute the
     %$COBOL command shown above, the job will log on as
     "COBOL,JANE.AP,DEV;OUTCLASS=,1" if no overriding variables have been set.

    * When MPEX builds the job stream, it will copy into it all the
     :FILE-equations that are then set in the session -- thus, if you say:

        %FILE LISTFILE;DEV=LP
        %FILE COPYLIB=MYCOPY.SOURCE
        %$COBOL AP###S,AP###P,*LISTFILE

     then the generated job stream will inherit the :FILE-equations for
     LISTFILE and COPYLIB (as well as any other :FILE-equations you might have
     in your session).

   * MPEX will also copy your current HPPATH variable to the job.

   * With the %SCHEDULE and %SUBMIT commands, you can also submit jobs that

        - log on as some other user ID,

        - with some other job name,

        - with some other :JOB card parameters,

        - at some other time (i.e.  with scheduling parameters).


MPEXSTREAMNOVERIFY_49
MPEXSTREAMNOVERIFY
Normally, whenever you do a $command, a %SUBMIT, or a %SCHEDULE, MPEX will
prompt you with "OK to stream (Y/N)?" to verify that you really want to submit
the job.  If you don't want this, just say

     :SETJCW MPEXSTREAMNOVERIFY=1

before you enter your "$", "%SUBMIT", or "%SCHEDULE" command -- MPEX will then
submit the jobs without prompting for verification.


MPEXSTREAMGOD_50
MPEXSTREAMGOD
If you have run GOD.PUB.VESOFT (documented elsewhere in this manual) in your
session and you do a

     :SETJCW MPEXSTREAMGOD=1

before you enter your "$", "%SUBMIT", or "%SCHEDULE" command, the job stream
created by MPEX will automatically run GOD.PUB.VESOFT as well.  If, however,
you have not run GOD in your session or you haven't set MPEXSTREAMGOD to 1, GOD
will not be run in the job stream.

After the job has completed, it will attempt to do a :TELL to your session to
let you know either that the job is done, or that an error occurred.

The message will include, if possible:

   * the name of the system (if the variable HPSYSNAME is set -- useful if you
     have multiple REMOTE sessions and jobs running);

   * the job name (usually the first 8 characters of the command you typed --
     see above);

   * the output spool file number of the job's $STDLIST (this lets you read the
     $STDLIST without having to do a %SHOWOUTJ to find it);

   * the text of the error message (if there was an error); and the name of the
     file on which the error occurred (if appropriate).

Normally, this :TELL is done to the job/session number that issued the $,
%SUBMIT, or $SCHEDULE command, but you can change this using the variable
MPEXTELLBACK.  Setting MPEXTELLBACK to "!!HPJOBNAME,!!HPUSER.!!HPACCOUNT" makes
MPEX jobs send the message to all sessions logged on with your job/session
name, your user ID, and your account name.  Setting it to "#S!!HPJOBNUM" (the
default) makes MPEX jobs send the message to your session specifically (if you
log off and log back on, no message will arrive).  You can set this variable to
anything you please -- e.g.  you might set it to "MANAGER.SYS" to make all jobs
send messages to MANAGER.SYS.

If you like, you can replace the :TELL command in the job with either a :TELLOP
or MPEX's %WARNF command by setting the MPEXTELLBACKCMD variable.

For example:

%SETVAR MPEXTELLBACKCMD "WARNF"

(Note, of course, that you must be :ALLOWed the :WARN command in order to use
%WARNF)

You can use MPEX's %PRINTO to view the $STDLIST of the last job you submitted
via "$", "%SUBMIT", "%SCHEDULE", or using SECURITY's STREAMX (see the
SECURITY User Manual for details on STREAMX) without having to specify the job
number or spool file number!  %PRINTO is documented in the MPEX Commands
section of this manual.

Sometimes, you might decide that you'd normally want all, say, %COBOL commands
or %EDIT commands to be done off-line.  If you say

   %SET DEFAULT,COBOL,$
   %SET DEFAULT,EDIT,$

you're telling MPEX "the default mode of execution for the %COBOL and %EDIT
commands is '$' (i.e.  offline) mode".  Then, whenever you say

   %COBOL ...

this command will be executed just as if it was prefixed with a "$".  If you
want to do it on-line (which would normally be the default), you'd have to say

   %!COBOL ...

telling MPEX to do the command in "!" (online) mode.

If you want to do %SET DEFAULTs, you probably want to include them into your
MPEXMGR.PUB.VESOFT, MPEXMGR.PUB.youracct, or MPEXMGR.yourgroup.youracct files
-- for more information, see the section "Specifying Commands To Be Executed
Every Time MPEX Is Entered".

IMPLIED RUN


Implied_RUN__51
Implied RUN

Syntax:   %programfile [.group [.account]]
          [[;INFO=] infostring]
          [[;PARM=] parmvalue]
          [;ENTRY=entrypoint]
          [;mperunparms] [ ...  ]

Examples: %DBUTIL               << perhaps to run DBUTIL.PUB.SYS...  >>
          %AP010.PUB            << run a specific program >>
          %MYPROG               << look in your own group first >>
          %MYPROG TESTING       << pass an INFO= string >>
          %MYPROG "X Y Z",10    << pass both an INFO= and a PARM= >>
                                << note ";PARM=" may be replaced by "," >>
          %MYPROG LIB=P;INFO="FOO";PRI=DS

If you type a command that is not a valid MPE/MPEX command or UDC, MPEX will
then try to find a program or command file with that name and execute it as if
you had typed :RUN or :XEQ at the beginning of the line.  Say that you type:

   %DBUTIL

(and presuming you do not have a UDC called "DBUTIL") MPEX will find the HP
supplied program DBUTIL.PUB.SYS and evaluate the command as if you'd entered:

   %DBUTIL.PUB.SYS

WHICH PROGRAM FILE IS RUN?

What do we mean by "try to find a program file with that name"? Well, if you
specify a qualified filename, e.g.

   %DBUTIL.PUB.SYS     or
   %AP010.PUB

then MPEX will simply run the program with that name (just as if you'd put "RUN
" at the beginning of your command).

Now, say that you specify a filename without a group or account, e.g.

   %DBUTIL     or
   %MYPROG

MPEX will then try to find a program with that name

   * first in your logon group,

   * then in the PUB group of your logon account,

   * and finally in PUB.SYS.

If DBUTIL is found in your logon group, it'll be run; if DBUTIL is not found in
your logon group or in your PUB group, but is found in PUB.SYS, then
DBUTIL.PUB.SYS will be run.

CHANGING THE SEARCH PATH


HPPATH_52
HPPATH
Of course, your natural question at this point must be "what if I want to
always search some other groups as well?".  What if you want to look in
PUB.SYS, then in UTIL.SYS, and then in PUB.PROD?

No problem! Just say

   %SETVAR HPPATH "!!HPGROUP,PUB,PUB.SYS,UTIL.SYS,PUB.PROD"

The HPPATH variable contains a list of groups to be searched, separated by
commas.

The first parameter is "!!HPGROUP", which refers to the logon group (see the
MPEX Variables section -- it'll also explain why we put two !s instead of just
one).  The second parameter is PUB -- the PUB group of the logon account; then
come PUB.SYS, UTIL.SYS, and PUB.PROD.  The default setting of HPPATH is

   %SETVAR HPPATH "!!HPGROUP,PUB,PUB.SYS"

Needless to say, you could delete some of these items as well as add new ones
-- saying

   %SETVAR HPPATH "UTIL.SYS,PUB.PROD"

tells MPEX to search only in the UTIL.SYS and PUB.PROD groups.

SPECIFYING INFO= AND PARM=


INFO__with_implied_RUN_53
INFO= with implied RUN


PARM__with_implied_RUN_54
PARM= with implied RUN
Simply saying

   %MAIN.PUB.VESOFT

is the same as saying

   %MAIN.PUB.VESOFT

Similarly, saying

   %MAIN.PUB.VESOFT "HELP",1                 or
   %MAIN.PUB.VESOFT INFO="HELP";PARM=1

is the same as saying

   %MAIN.PUB.VESOFT;INFO="HELP";PARM=1


ENTRY__55
ENTRY=
If you want to specify an entrypoint, simply use the ;ENTRY= keyword.  You may
also specify any other parameters -- ;LIB=, ;MAXDATA=, ;STDIN=, etc.  -- that
you can specify on the %RUN command.  (Note that this is different from the
MPE/iX CI, which only lets you specify ;INFO= and ;PARM=.)

COMMAND FILES


Command_files__56
Command files

Syntax:   %cmdfile [.group [.acct]]
             [parmvalue] [, ...  ]
             [parmname=parmvalue] [; ...  ]

Examples: %MYFILE 10, 20, 30
          %MYFILE FRAMASTATS=40;THINGAMABOBS=10

In the "IMPLIED RUN" discussion above, we said that if you enter a command
that's not a valid MPE or MPEX command (or UDC), MPEX will look for a file with
that name in

   * your logon group,

   * the PUB group of your logon account,
   * and PUB.SYS.

If MPEX finds a program file, it'll :RUN it (just as if you'd entered a %RUN
command).  What if it finds a non-program file?

Well, if MPEX finds a normal ASCII file, it will assume that it is a COMMAND
FILE, and will execute all the MPE commands stored in this command file.  For
instance, if you create a file called SCHEMA.PUB.SYS that contains the lines


PARM_57
PARM

   PARM TEXTFILE, LISTFILE="$STDLIST"
   FILE DBSTEXT=!TEXTFILE
   FILE DBSLIST=!LISTFILE
   RUN DBSCHEMA.PUB.SYS;PARM=3

and you then type

   %SCHEMA APBASESC,*LP

MPEX will execute the commands

   %FILE DBSTEXT=APBASESC
   %FILE DBSLIST=*LP
   %DBSCHEMA.PUB.SYS;PARM=3

In other words, a command file is very much like a UDC; it may have parameters,
OPTIONs, defaults, etc.  The only differences are:

   * The command file need not be :SETCATALOGed.  Any command file that is in
     your search path (see the discussion of the HPPATH variable below) is
     available to you.

     The new %SCHEMA command is implemented by the very existence of the
     command file SCHEMA.PUB.SYS.

   * The header line (if any) should start with "PARM", e.g.

        PARM TEXTFILE, LISTFILE="$STDLIST"

     rather than with the UDC name -- the name of the command is already
     defined by the name of the command file.  (The "PARM" line is not
     required.  If you don't intend to pass any parameters to the command file,
     don't include a "PARM" line.) You can have multiple "PARM" lines, rather
     than trying to squeeze all of your parameters into one line.

   * Naturally, each command file can define only one command (as opposed to
     UDC files, each of which may define many commands).

The advantages of UDCs are

   * They support  OPTION LOGON (both command files and UDCs support all the
     other options).

   * They may be used for security purposes, to block out particular MPE
     commands.

   * They are somewhat faster at command execution time, since they don't
     require a file open; on the other hand, they're slower at logon time.

SPECIAL SECURITY NOTE

MPEX allows a user to execute a command file even if he only has eXecute (not
Read) access to it.  This way, you can create a command file that may contain
sensitive information (such as lockwords) that you don't want a user to see.
Although this is technically incompatible with MPE/iX, we believe that it is
substantially more useful.

COMMAND FILES AND "HPPATH"

As we mentioned above, command files (just like program files or implied run
commands) are looked for

   * first in your logon group,

   * then in the PUB group of your logon account,

   * and then in PUB.SYS.

If you want to change this search sequence, you can use the same HPPATH
variable used for the IMPLIED RUN searching, described earlier in this chapter.
For instance,

   %SETVAR HPPATH "!!HPGROUP,PUB.SYS,UTIL.SYS,PUB.PROD"

indicates that both programs to be implicitly :RUN and command files are to be
searched for first in your logon group, then in PUB.SYS, then in UTIL.SYS, and
then in PUB.PROD.

ANYPARM AND REST$ PARAMETERS


ANYPARM_and_REST__58
ANYPARM and REST$

Consider this: how would you implement the MPE :FCOPY command as a UDC (command
files being pretty similar to UDCs)? You might say

   FCOPY !CMD
   RUN FCOPY.PUB.SYS;INFO="!CMD"

but then if you type

   :FCOPY FROM=A;TO=B;NEW

MPE will reject it -- the FCOPY UDC (or command file) was declared with only
one parameter, but you entered three ("FROM=A", "TO=B", and "NEW").  Since ";"
(as well as ",", " ", and to some extent "=") are considered by MPE to be
delimiters, the parameter to the FCOPY UDC must not include any of these
delimiters, or else it must be enclosed in quotes.

What you need is some way of saying "consider the rest of this command to be a
single parameter".  For instance, you might say:

   FCOPY REST$CMD
   RUN FCOPY.PUB.SYS;INFO="!CMD"

The "REST$" prefix in the parameter name (note that the REST$ is only specified
in the header record, not every time !CMD is mentioned) indicates that this is
a "rest-of-the-line" parameter.  When you type

   %FCOPY FROM=A;TO=B;NEW

MPEX will consider the entire parameter string -- "FROM=A;TO=B;NEW" -- to be
one parameter (CMD).

The REST$ parameter must obviously be the last parameter of the command, but
need not be the only one.  You might, for instance, want to define a UDC such
as

   PROCESS FROMFILE, TOFILE, REST$PARMS
   FILE MYFROM=!FROMFILE
   FILE MYTO=!TOFILE
   RUN MYPROG;INFO="!PARMS"

Now, when you say

   PROCESS A, B, C, D, E

the "FROMFILE" parameter will be set to "A", the "TOFILE" parameter to "B", and
the "PARMS" parameter to "C, D, E".  The REST$ parameter is set to the
REMAINDER of the command string after all the other parameters have been
assigned.

Of course, this is available only in UDCs and command files that are executed
from MPEX.  Naturally, if you try to execute from MPE a UDC that includes a
REST$ parameter, you won't get very far.

Unfortunately, MPE/iX won't even let :SETCATALOG a UDC that has "REST$" in the
first line.  However, MPE/iX has a feature (fully supported in MPEX on both
MPE/V and MPE/iX), ANYPARM, that is quite similar to REST$.  Note: while REST$
can be the last parameter on the last PARM line, ANYPARM must be the last PARM
line all by itself.

For example,

   PARM A, B, C
   ANYPARM D
   ...

means that parameter "D" is to be set to the rest of the command line (just
like "REST$") -- thus, if the above command file is passed a parameter string
of "ALPHA, BETA, GAMMA, DELTA, EPSILON, ZETA", parm A will have the value
"ALPHA", B will be "BETA", C will be "GAMMA", and D will be "DELTA, EPSILON,
ZETA" (with the commas!).

Of course, like any other parameter, both REST$ and ANYPARM parameters allow
defaults (which makes them "optional").  However, if you want them to default
to a null string (""), you must do one of the following:

PARM REST$FOOBAR=![""]
     or
ANYPARM FOOBAR=![""]

If you just say 'FOOBAR=""', the variable FOOBAR will actually contain the
quote characters.

Another feature that you may find essential when using ANYPARM and/or REST$ is
our CMDPARM(...) function.  Please see Appendix for details.

CS$ PARAMETERS


CS__59
CS$

One other option we have for UDCs and command files is the CS$ option:

   PARM CS$FILESET, NEWDEV
   ALTFILE !FILESET; FLIMIT=EOF*2; DEV=!NEWDEV

What does this command file (let's call it MOVETHEM) do? (We know that it's a
command file because its header starts with "PARM".)

Well, it takes two parameters -- an MPEX fileset and a new device name -- and
%ALTFILEs all the files in the fileset to

   * have a file limit that's double their current number of records, and

   * reside on the device indicated by NEWDEV.

So what's all this CS$ stuff? Well, say that we type

   %MOVETHEM @.DATA(CODE="" and SECTORS>1000), 3

We're asking MPEX to move to device 3 the files in the DATA group that have
code="" (i.e.  0) and use more than 1000 sectors.

This seems like a reasonable enough command; unfortunately, both "=" and " "
(blank) are considered by MPE to be parameter delimiters.  If %MOVETHEM were a
normal MPE UDC (or a normal MPE/iX command file), MPEX would reject the command
we just showed unless the entire fileset parameter was enclosed in quotes.

The CS$ before the FILESET parameter in the command file header stands for
"Comma/Semicolon".  It says that the only delimiters that should be recognized
for the parameter are Comma and Semicolon, not space or the equal sign.  It
also indicates that any delimiters inside parentheses (e.g.  in selection
conditions) are to be ignored.

As you can see, this feature was designed especially for MPEX filesets, and is
most useful when you're passing MPEX fileset parameters.

DETERMINING WHETHER YOU'RE IN MPEX OR NOT


INSIDEMPEX_60
INSIDEMPEX
Sometimes, you may want to write a command file or UDC that works successfully
from MPEX and in MPE (MPE/V or MPE/iX), but, when executed from MPEX, uses some
special MPEX feature.

MPEX treats the JCW "INSIDEMPEX" as a special sort of JCW.  When you enter
MPEX, MPEX does a ":SETJCW INSIDEMPEX=0", but whenever you try to reference
INSIDEMPEX from an MPEX command, MPEX will always return the value 1 (even
though its "true" value is 0).  This way, a command file or a UDC that is
executed from within MPEX will see INSIDEMPEX as being equal to 1, but when
executed from MPE, will see INSIDEMPEX as being equal to 0.  Thus, the command
file or UDC can say "IF INSIDEMPEX=1 THEN" or "IF INSIDEMPEX=0 THEN" to tell if
it's in MPEX or not.

The only possible problem arises if the command file or UDC is executed from
within MPE before the first run of MPEX in the session, in which case the
INSIDEMPEX JCW will not be set, and an IF INSIDEMPEX=1 THEN will get a CI
error.  You can solve this by adding a :SETJCW INSIDEMPEX=0 to the beginning of
the command files/UDCs that you wish to test INSIDEMPEX within, either at the
beginning or right before you test it.  Then, when you test it in MPEX, MPEX
will tell you it is 1.  If you test it outside of MPEX, MPE will tell you it is
0.

REDIRECTING COMMAND INPUT AND OUTPUT


Redirecting_command_input_output__61
Redirecting command input/output


__62
>


___63
>>


__64
<
MPEX lets you very easily redirect the input and output of any MPEX command,
including command file execution, %RUN, etc.

Simply specify in the command

   <infile,                  e.g.  %RUN MYPROG;INFO="XYZ" <DATAFIL
   >outfile,                 e.g.  %SHOWOUT JOB=@;SP >OUTDATA
   >>outfile (to append), e.g.  %ECHO Executing step 5 >>LOGFILE

This is thus both a convenient shorthand for ;STDIN= and ;STDLIST= on :RUN
commands and implied RUN, and a way of redirecting commands (like %SHOWOUT and
%ECHO) and command files that could not have been easily redirected before.

* The <, >, and >> can be specified anywhere in the command, so long as the
  filename is followed by a blank or some such delimiter.

* If you specify "<infile", MPEX will first try to use the temporary file with
  that name, and if that doesn't exist, then the permanent file.  If you
  specify ">outfile" or ">>outfile", MPEX will try to write to or append to the
  temporary file with that name, and if that doesn't exist, will create a new
  temporary file.  If you want to output to a permanent file, you must use a
  :FILE equation with ",OLD" (for old files) or ";SAVE" (for new files).  This
  might be somewhat inconvenient, but we have to do this to be compatible with
  MPE/iX.

* This syntax may present some compatibility problems, e.g.  if you have
  existing commands that contain <, >, or >> followed by valid-seeming
  filenames (which shouldn't be very common; we've noticed it most often in
  ECHO commands).  The MPE/iX implementation of this feature suffers from
  similar problems.

    - To make it less likely that problems will occur, the commands CALC,
      COMMENT, ELSEIF, IF, SETJCW, SETVAR, TELL, TELLOP, WARN, WARNF, WHILE and
      such do not allow input or output redirection (which wouldn't make sense
      for them anyway).

    - Also, <, >, and >> are not resolved inside quoted strings, ![ ...  ]
      constructs, or (this is specific to MPEX, not MPE/iX) inside parentheses.
      Note that the apostrophe is considered a quote character, so if you use a
      contraction in an echo statement, it won't work the way you might expect
      -- MPEX sees the apostrophe as an opening quote, so everything until the
      next apostrophe or the end of the line is treated as "inside" a quoted
      string.  For example:

        %ECHO This won't work >>workfile

      will display everything to the screen and will not put the string "This
      won't work" into the workfile.  In order to avoid this problem, MPEX
      allows you to specify the output file anywhere in the line, even as the
      first item, so to actually put a string with just one quote character
      into a file, use the following:

        :ECHO >>workfile This will work, even with a ' character.


__65
!
    - If you need to embed a <, >, or >> into a command, you may prefix them
      with a "!", e.g.  "ECHO VAR1!>VAR2".

* By default (unless overridden with a file equation), the output files are
  built with variable-length records, no carriage control, and a file limit of
  10,000 (which practically means that more than 10,000 variable-length records
  will fit into the file).

* By default, any command execution errors for an output-redirected command
  (except errors in opening the redirection files) will be sent to the output
  file.  If you want them to go to the terminal, set the variable HPERRSTOLIST
  to TRUE (see Appendix).

CHECKING MPEX COMMAND SUCCESS


Checking_MPEX_command_success__66
Checking MPEX command success

Note: if you are interested in error-handling, you should also look at the MPEX
%TRAPERROR command.  It provides an advanced, easy to use, mechanism for
handling errors in jobs, command files, etc.

How can you tell -- in a job stream, in a command file, or in a UDC -- whether
an MPEX command succeeded?


CIERROR_67
CIERROR
Well, if it is a normal MPE command (like :BUILD or :FILE) or one of our
advanced fileset handling commands (like %RENAME or %PURGE) in which only a
single file was specified, we'll set the CIERROR JCW as MPE normally would;
we'll even set two new JCWs:


FSERROR_68
FSERROR
   * FSERROR, which indicates the file system error (if any) encountered while
     executing the command.


CIERRORISWARN_69
CIERRORISWARN
   * CIERRORISWARN, which is 1 if the CI error was a warning and 0 if it was a
     true error.

Similarly, if we encounter a truly global error in one of MPEX's own commands
-- e.g.  you specified a syntactically invalid fileset -- we set the CIERROR
JCW to one of our own error numbers (largely 30,000 and above).  At the very
least it will abort the execution of the command file, UDC, or job; and, if you
do an :IF CIERROR<>0 THEN or something like that, you'll see that an error
occurred.

Now, say that you're doing a fileset %ALTFILE.  67 files were successfully
altered but 4 couldn't be altered because of file system errors (security, file
in use, etc.).  What should we do?

Well, on "file-level errors" -- errors that occur on a specific file -- we do
not abort the command file, UDC, or MPEX job; in fact, we usually won't even
set the JCWs mentioned above.

However, we do provide you with two new JCWs that tell you in great detail how
successful the command was:


MPEXNUMSUCCEEDED_70
MPEXNUMSUCCEEDED
   * MPEXNUMSUCCEEDED is set to the number of files successfully processed.


MPEXNUMFAILED_71
MPEXNUMFAILED
   * MPEXNUMFAILED is set to the number of files on which errors were
     encountered.

With these two JCWs, you can do all the checking you want.  You might say (in
your job stream)

   %IF MPEXNUMFAILED>0 THEN
   %  TELLOP AT LEAST ONE ERROR OCCURRED!
   %ENDIF

(to check if there was at least one failure), or

   %LISTF @.@(CREATOR<>"MANAGER")
   %IF MPEXNUMSUCCEEDED=0 THEN
   %  TELLOP NO FILES CREATED BY NON-MANAGER USERS
   %ENDIF

or even (if you want to get really fancy)

   %COBOL AP@.SOURCE,AP@.PUB
   %IF MPEXNUMFAILED>(MPEXNUMFAILED+MPEXNUMSUCCEEDED)/10 THEN
   %  TELLOP COMPILE MORE THAN 10% BAD, CALL THE PROGRAMMER
   %  TELLOP AND TELL HIM TO COME IN THIS WEEKEND.
   %ENDIF

SETTING DEFAULT PARMS FOR MPEX COMMANDS


Setting_default_parms_for_MPEX_commands__72
Setting default parms for MPEX commands


VESOFTDEFAULTALARM_73
VESOFTDEFAULTALARM


VESOFTDEFAULTALTFILE_74
VESOFTDEFAULTALTFILE


VESOFTDEFAULTALTJOB_75
VESOFTDEFAULTALTJOB


VESOFTDEFAULTBREAKJOB_76
VESOFTDEFAULTBREAKJOB


VESOFTDEFAULTBYE_77
VESOFTDEFAULTBYE


VESOFTDEFAULTCALENDAR_78
VESOFTDEFAULTCALENDAR


VESOFTDEFAULTCHLOGON_79
VESOFTDEFAULTCHLOGON


VESOFTDEFAULTCOPY_80
VESOFTDEFAULTCOPY


VESOFTDEFAULTDEVCONTROL_81
VESOFTDEFAULTDEVCONTROL


VESOFTDEFAULTDOSAVED_82
VESOFTDEFAULTDOSAVED


VESOFTDEFAULTIDENTIFY_83
VESOFTDEFAULTIDENTIFY


VESOFTDEFAULTIMPRUN_84
VESOFTDEFAULTIMPRUN


VESOFTDEFAULTPAUSEJOB_85
VESOFTDEFAULTPAUSEJOB


VESOFTDEFAULTPREP_86
VESOFTDEFAULTPREP


VESOFTDEFAULTPREPRUN_87
VESOFTDEFAULTPREPRUN


VESOFTDEFAULTPRINT_88
VESOFTDEFAULTPRINT


VESOFTDEFAULTRENAME_89
VESOFTDEFAULTRENAME


VESOFTDEFAULTRESUMEJOB_90
VESOFTDEFAULTRESUMEJOB


VESOFTDEFAULTRUN_91
VESOFTDEFAULTRUN


VESOFTDEFAULTSAVEJOB_92
VESOFTDEFAULTSAVEJOB


VESOFTDEFAULTSHOWALARM_93
VESOFTDEFAULTSHOWALARM


VESOFTDEFAULTSHOWJOB_94
VESOFTDEFAULTSHOWJOB


VESOFTDEFAULTSHOWME_95
VESOFTDEFAULTSHOWME


VESOFTDEFAULTSHOWPROC_96
VESOFTDEFAULTSHOWPROC
You can set any default parameters you want to for the %ABORTJOB, %ALTFILE,
%ALTSCHED, %ALARM, %ALTJOB, %BREAKJOB, %BYE, %CALENDAR, %CHLOGON, %COPY,
%DEVCONTROL %DOSAVED, %IDENTIFY, %LISTJOB, %NEWLINK, %PAUSEJOB, %PREP,
%PREPRUN, %PRINT, %PRINTO, %PURGE, %PURGELINK, %RENAME, %RESUMEJOB, %RUN (and
implied RUN), %SAVEJOB, %SHOWALARM, %SHOWJOB, %SHOWME, %SHOWPROC, %SHOWSAVED,
%SPOONFEED, and %SPOONINIT commands -- e.g.:

   %SETVAR VESOFTDEFAULTALTFILE ";KEEPAMDATES;XLTRIM"
   %SETVAR VESOFTDEFAULTCOPY    ";KEEPAMDATES;KEEPATTR"
   %SETVAR VESOFTDEFAULTPRINT   ";KEEPAMDATES;PAGEHEAD"
   %SETVAR VESOFTDEFAULTCHLOGON ";KEEPCAPS"

To automatically kill any son processes that might suspend instead of
terminating, set the following default:

   %SETVAR VESOFTDEFAULTRUN ";KILL"

WARNING:    setting this variable to this value globally (in
            MPEXMGR.PUB.VESOFT, for instance) will have adverse side effects on
            the operation of our software.

   %SETVAR VESOFTDEFAULTPREP ";CAP=PH,DS;MAXDATA=30000;FPMAP"
   %SETVAR VESOFTDEFAULTPREPRUN VESOFTDEFAULTRUN+VESOFTDEFAULTPREP

       (to set the %PREPRUN defaults to be equal to the %PREP defaults
       concatenated with the %RUN defaults)

   %SETVAR VESOFTDEFAULTIMPRUN ";LIB=P;MAXDATA=30000"

      (for any programs run via implied :RUN, i.e.  by just specifying the name
      of the program)

   %SETVAR VESOFTDEFAULTBREAKJOB  ";NOVERIFY"
   %SETVAR VESOFTDEFAULTRESUMEJOB ";NOVERIFY"

      (so that %BREAKJOB and %RESUMEJOB don't ask for verification)

The values of the VESOFTDEFAULTxxx variables must start with ";"s, as shown
above.

If you want to use non-default settings, you certainly can -- for instance, if
VESOFTDEFAULTPREP is set to ";CAP=PH,DS;MAXDATA=30000;FPMAP" and you do a :PREP
;CAP=PM, it will do the prep with PM capability and without PH and DS (since
your ;CAP= overrides the default ;CAP=), but will still use the ;MAXDATA=30000
and ;FPMAP.

If the default value that you want to override doesn't have an option that can
turn it off (e.g.  ;KEEPAMDATES), and you don't want to use this default in a
particular command, you must delete the appropriate VESOFTDEFAULTxxx variable
and then re-set it later.

RESTRICTING MPEX COMMANDS TO ONLY WORK ON CERTAIN FILES


Restricting_MPEX_commands_to_only_work_on_certain_files__97
Restricting MPEX commands to only work on certain files


MPEXCRITRESTRICTxxx_98
MPEXCRITRESTRICTxxx

Sometimes you know that certain MPEX fileset-handling commands don't make any
sense (or can even do damage) when performed on certain types of files.  For
instance, the %EDIT command can't work on binary files because EDITOR can only
handle ASCII files; furthermore, you might not want it to operate on KSAM
files, since a /KEEP of a KSAM file will keep it as a "flat" file, which will
preserve the data but destroy the KSAM file structure.

To implement such restrictions, just say:

   %SETVAR MPEXCRITRESTRICTEDIT "ISASCII and NOT ISKSAM"

and the %EDIT command will behave as if you included the selection condition
(ISASCII and NOT ISKSAM) -- i.e.  select only ASCII files that aren't KSAM
files -- on the fileset.  (Of course, this will also work if you explicitly
specified a selection condition on the fileset; both conditions would then be
used.)

If you want this sort of restriction to work for all users all the time, you
can just put the %SETVAR into the MPEXMGR.PUB.VESOFT file; needless to say, a
similar %SETVAR would work to impose new selection conditions for other
commands -- just do a %SETVAR MPEXCRITRESTRICTcmdname.

If you want to temporarily turn off this restriction, you can just %DELETEVAR
the appropriate variable.  If the %SETVAR is in MPEXMGR.PUB.VESOFT, the
variable will be reinitialized the next time you enter MPEX.


MPEX_Variables__General_Discussion__99
MPEX Variables: General Discussion

   %SETVAR FNAME "MYFILE.PUB.TEST"

   %SHOWVAR F@
   FLUGELHORN = 172345
   FNAME = MYFILE.PUB.TEST
   FUNNY = TRUE

   %CALC STR(FNAME,3,6)
   FILE.P

   %ECHO FILE = !FNAME.
   FILE = MYFILE.PUB.TEST.

   %DELETEVAR FNAME
   %SHOWVAR F@
   FLUGELHORN = 172345
   FUNNY = TRUE

An MPEX variable -- just like a COBOL or PASCAL variable -- stores data.  MPEX
variables:

   * Are similar to JCWs, but may contain strings, boolean (true/false) values,
     or 32-bit integers.

   * Are set with the %SETVAR command.

   * Can have their values input interactively using the %INPUT command.

   * May be looked at with the %SHOWVAR command.

   * Can be used in any MPEX expression, including:

      - %CALC/%SETVAR expressions,

      - %IF/%WHILE expressions,

      - and MPEX selection conditions.

   * Can be substituted into any MPEX command file much like UDC parameters can
     be substituted into commands within UDCs.

   * Stay around for the duration of your job or session (not just while you're
     running MPEX).


MPE_V_and_MPE_iX_differences__MPEX_variables_100
MPE/V and MPE/iX differences: MPEX variables
   * If you're running MPEX on an MPE/iX machine, MPEX variables are stored as
     MPE/iX variables; on MPE/V, MPEX keeps its variables in a special table.

USING MPEX VARIABLES


Using_MPEX_variables__101
Using MPEX variables

MPEX variables, once they're set using the %SETVAR or %INPUT commands (which
are documented in more detail elsewhere in this manual) can be used in one of
several ways:

   * Whenever MPEX expects an expression -- in

        - %IF statements,

        - %CALC statements,

        - %WHILE statements,

        - %SETVAR statements,

        - MPEX fileset selection criteria, and

        - MPEX flexible LISTF template files

     you can use MPEX variables.  For instance, if CMDPARMS is a string
     variable, you might say

   %IF STR(CMDPARMS,1,1)="X" THEN

     thus using CMDPARMS as an element in the expression STR(CMDPARMS,1,1)="X".


__102
!
   * When MPEX does not expect an expression, you can substitute the value of a
     variable by prefixing it with an "!":

   %:BUILD !FNAME;REC=4095,,,ASCII

     Here, if FNAME is a variable, its value is textually substituted in place
     of the string "!FNAME".  If FNAME's value is XYZZY, the above %:BUILD
     command is exactly identical to the command

   %:BUILD XYZZY;REC=4095,,,ASCII

     Of course, this is very much like the way UDC parameter substitution has
     always worked in MPE.


_________103
!" ... "
   * Instead of saying !VARNAME, you might also say !"VARNAME", e.g.

   %:BUILD Y!"MODULE"DAT;CODE=123;REC=-64,,,ASCII

     As you see, the !"MODULE" is immediately followed by the alphanumeric
     string DAT -- if we had said

   %:BUILD Y!MODULEDAT;CODE=123;REC=-64,,,ASCII

     MPEX would have tried to find the value of the variable MODULEDAT rather
     than of MODULE.  !"VARNAME" is thus identical to !VARNAME except that it
     can be used even if it's followed by an alphabetic or numeric character.


_________104
![ ... ]
   * An even more powerful construct is ![expression], e.g.

   %:BUILD !FNAME;DISC=![4*MAXUSERS+MAXPROGS],32

     The expression between the ![ and the ] -- 4*MAXUSERS+MAXPROGS -- is
     evaluated and is substituted for the entire ![4*MAXUSERS+MAXPROGS]
     construct.  If FNAME were MYFILE, MAXUSERS were 100, and MAXPROGS were 25,
     the above command would be equivalent to

   %:BUILD MYFILE;DISC=425,32

The !xxx, !"xxx", and ![xxx] constructs are some of the most powerful features
of MPEX variables, since they let you very easily parameterize MPEX commands --
in UDCs, in command files, or in jobs -- to do exactly what you want them to
do.  They make MPEX programming very easy and very powerful.

SETTING MPEX VARIABLES


Setting_MPEX_variables__105
Setting MPEX variables

Of course, before an MPEX variable is used, it must first be set.  Several ways
are available for doing this:

   * The %SETVAR command, which stores the value of an expression (or of a
     constant) in an MPEX variable, e.g.

   %SETVAR MYFILE "XYZ.PUB.DEV"

or

   %SETVAR MYFILE "S"+MODULENAME+".DEV.VESOFT"

     (the second %SETVAR, as you see, sets MYFILE to the value of an expression
     that involves MODULENAME, another variable).

   * The %INPUT command, which prompts the user for input, e.g.

    %INPUT MODULENAME; PROMPT="Enter module name: "

   * A number of MPEX variables are predefined (see the Predefined Variables
     chapter in Appendix).  These include such useful variables as

        - HPUSER, a string containing the logon user ID;

        - HPLDEVIN, an integer containing the device number of the logon
          terminal;

        - HPINTERACTIVE -- TRUE in a session, FALSE in a job;

        - HPUSERCAPF, a string containing a list of all the capabilities a user
          possesses;

        - and many more.

   * Some other variables are specially defined for MPEX purposes, and may be
     set and/or looked at by MPEX -- see the Special Variables Used By MPEX
     section in this chapter.

LOCAL VARIABLES


Local_variables__106
Local variables

Often, within a command file, you will create variables that are only intended
for use within that particular command file.  You don't want these variables to
conflict with existing, global variables you may have set (or with predefined
HP or VESOFT variables), and you want to delete these variables after the
command file is done executing.  One way to do this is to precede the variable
name with the name of the command file; i.e.  in a command file named "FIDGET",
you might use variables names FIDGET_NAME, FIDGET_ADDRESS, FIDGET_PARM, etc.
Then, at the end of the command file, you could delete all of these variables
with the command: DELETEVAR FIDGET_@

But what you really want are local variables; and MPEX has them!


_SETLVAR_107
%SETLVAR


_DELETELVAR_108
%DELETELVAR


_SHOWLVAR_109
%SHOWLVAR
Local variables are quite similar to "regular", global variables; you create
them with the "%SETLVAR" command (instead of "%SETVAR" -- notice the "L" ),
delete them with "%DELETELVAR" (instead of "%DELETEVAR" -- again, notice the
"L"), and view them with "%SHOWLVAR" (instead of "%SHOWVAR" -- there's that "L"
again).  Like global variables, local variables can be of type string, integer,
or boolean.

Local variables have three important properties:

   * Unlike global variables, they are automatically deleted when the command
     file within which they were created terminates! (If you create a local
     variable by typing "%SETLVAR" directly within MPEX instead of in a command
     file, the variable will last until you exit MPEX).

   * Local variables created in one command file are not accessible within any
     other command file! (Local variables created "directly" within MPEX do not
     exist within any command file at all.)

   * When both a local and a global variable exist with the same name, the
     local variable will be used, e.g.  the result of

   %SETVAR  MYVAR "global"
   %SETLVAR MYVAR "local"
   %ECHO the !MYVAR variable will be used.

     is "the local variable will be used."

Note that this can be quite useful for testing.  Say you have a command file
that behaves differently in batch than it does on-line, by testing the variable
HPJOBTYPE, and you want to observe the batch behavior while running it on-line.
If you attempt to "SETVAR HPJOBTYPE 'J'", you'll get to see the error message
"ASSIGNMENT TO VARIABLE NOT ALLOWED: READONLY.  (CIERR 8115)".

But, if you add the line "SETLVAR HPJOBTYPE 'J'" to the beginning of the
command file, you can perform your test! And you don't have to worry about
forgetting to delete the variable later so that it won't interfere with other
command files -- local variables (as we said above) are deleted automatically!

OTHER VARIABLE FEATURES


Other_variable_features__110
Other variable features

Other variable-handling commands -- remember, all of them are documented in the
MPEX COMMANDS section -- include:

   * %DELETEVAR, which deletes a variable or a set of variables.

   * %SHOWVAR, which shows the values of a set of variables.

   * %SET VARTRACE (and %SET NOVARTRACE), which shows all changes to the values
     of variables (useful in debugging).

Some other things you might want to know about variables are:

   * If you're trying to look at the value of a variable (in an expression --
     e.g.  in a %CALC command -- or when you're substituting with ! or ![...]),
     and a JCW with that name exists, the value of that JCW will be gotten.

     For instance, if you say

   %SETVAR TEMPERR CIERROR

or

   %ECHO CI error #!CIERROR

     then MPEX will retrieve and substitute the CIERROR JCW just as if it were
     an MPEX variable.


MPE_V_and_MPE_iX_differences___SETVAR_or__INPUT_to_JCW_111
MPE/V and MPE/iX differences: %SETVAR or %INPUT to JCW
     On MPE/iX if you do an %INPUT or a %SETVAR into a variable whose name is
     that of an existing JCW, the JCW will be "changed" into a variable.  On
     MPE/V the JCW will be set unless you are attempting to set it to a string,
     boolean, or a value >65535, in which case you will get CIERR 8135.

     This is because MPEX variables are more flexible than JCWs, and may
     contain strings, 32-bit integers, and boolean values, where MPE JCWs can
     only contain 16-bit integers.

   * Say that an MPEX string variable (one whose value is a string rather than
     an integer or a boolean) contains in its value an !, e.g.

   %SHOWVAR FNAME
   FNAME = MYFILE.!HPGROUP.SYS

     Then, whenever you substitute the variable with an ! or a !"..." (but not
     a ![...]), the variable will be recursively substituted.  Say that your
     logon group is JACK (which means that the predefined variable HPGROUP
     would be set to JACK); when you say

   %ECHO Filename = !FNAME

     you won't just see

   Filename = MYFILE.!HPGROUP.SYS

     (which would be the case if MPEX merely substituted the value of FNAME for
     the string !FNAME), but will instead see

   Filename = MYFILE.JACK.SYS

     Instead of just having variables substituted once, variables were
     substituted repeatedly until no more substitutions were possible.  Another
     example might be:

   %SHOWVAR
   A = ABACUS
   B = B[!A]
   C = C/!B\line   D = D(!C)
   %ECHO D is !D
   D is D(C/B[ABACUS]

     As you see, !D was recursively substituted until all the variable
     references -- !C, !B, and !A -- were satisfied.

     As you can also see, %SHOWVAR command does not do recursive substitution
     -- neither do the ![...] construct or any expression evaluation commands
     (e.g.  %CALC).  Only ! and !"..." do recursive substitution.

     (If this confuses you, it's OK -- it confuses me, too.  I'm sure it could
     be quite useful in some cases, but it's pretty complicated.  I really only
     put it in for compatibility with MPE/iX.)

A FEW COMMENTS ABOUT THE "!" CHARACTER


A_few_comments_about_the_____character_112
A few comments about the "!" character

The fact that ! is a special prefix character (which causes a substitution of
the expression that follows) creates some problems.  If you say

   %ECHO !HPUSER

then MPEX will output your user name (the value of the variable HPUSER).  But,
what if you really want to output the string "!HPUSER" -- an exclamation mark
followed by "HPUSER"?

To do this, we use the old MPE UDC convention of doubling the exclamation mark:

   %ECHO !HPUSER
   MANAGER
   %ECHO !!HPUSER
   !HPUSER

When MPEX reads a command and substitutes variables, it replaces all "!!"s by
"!"s and does not substitute for whatever variable follows it.

This may seem simple enough, but it can cause a few interesting quirks.  For
instance, say that you enter

   %TELLOP PLEASE MOUNT THE TAPE!!!!!

The message that the operator will see is

   FROM/.../PLEASE MOUNT THE TAPE!!!

It includes only THREE exclamation marks.  When you input "!!!!!", MPEX
replaced each pair of exclamation marks by a single exclamation mark, thus
changing exclamation marks 1 and 2 into a single "!", changing exclamation
marks 3 and 4 into a single "!", and leaving exclamation mark 5 as a single "!"
(since it is neither doubled nor has a variable name following it).

Got all that? Well, if you think you did, explain what is wrong with the
command

   %SETVAR MPEXPROMPT "!HPTIMEF: "

On the surface, it seems that you're setting the MPEXPROMPT variable so that
MPEX will always prompt you with the current time -- that way, at 1:35 PM, MPEX
will prompt you with
   1:35 PM:
and at 2:02 PM, MPEX will prompt you with
   2:02 PM:
It seems that this should happen, but it won't.  The first thing that MPEX does
when executing a command is resolve all the !s.  Thus, right after you enter
(say, at 12:29 PM) the command

   %SETVAR MPEXPROMPT "!HPTIMEF: "

MPEX will resolve the !s and turn the command into

   %SETVAR MPEXPROMPT "12:29 PM: "

The variable "MPEXPROMPT" will be set to the constant string "12:29 PM: ".
Thus, for the rest of day you'll be prompted with "12:29 PM: ".

What you should say instead is

   %SETVAR MPEXPROMPT "!!HPTIMEF: "

Now, when MPEX resolves the !s, it'll translate the command into

   %SETVAR MPEXPROMPT "!HPTIMEF: "

The variable MPEXPROMPT will be set to the string "!HPTIMEF: ".  Then, when
MPEX actually prints the variable, it'll resolve the !s again, prompting you
with

   1:35 PM:

Because the MPEXPROMPT variable was set to the literal string "!HPTIMEF: ", the
HPTIMEF resolution isn't done until the prompt is actually printed (which is
exactly the right time for it to be done).

SPECIAL VARIABLES USED BY MPEX


Special_variables_used_by_MPEX__113
Special variables used by MPEX

There are a number of very useful predefined variables (such as HPUSER,
HPDATEF, HPINTERACTIVE, etc.) that are described in great detail in Appendix.
They are largely read-only and return information about your current session or
about the system environment.

There are a few other predefined variables that are specific to MPEX.  Some of
them are set by MPEX, but others can be set by you to control MPEX's behavior.
Here they are:


MPEXCMDTRACE_JCW__114
MPEXCMDTRACE JCW
   * MPEXCMDTRACE [INT] (may be either a JCW or a variable)

     If this is set to 1, all commands that MPEX executes (including those that
     come from UDCs, from command files, from :WHILE loops, etc.) will be
     output to the terminal.  This can be quite useful if you have some
     mysterious 'bug' in one of your complicated command files and you want to
     know exactly what's going on.

     MPEXCMDTRACE is not checked if a %SET NOCMDTRACECHECK is in effect (see
     the "%SET [NO]CMDTRACECHECK" command).

     [Note: this JCW/variable can also be used to debug STREAMX jobs and
     SECURITY/3000 MENUs.]


MPEXPROMPT_115
MPEXPROMPT
   * MPEXPROMPT [STR]

     Indicates how MPEX is to prompt you for a command (default "%").  For more
     information, see "Changing The MPEX Prompt" in the Running MPEX section.


HPSYSNAME_116
HPSYSNAME
   * HPSYSNAME [STR]

     Supplies a "system name" to include in the heading of all MPEX %LISTF
     output.  Also used by SECURITY/3000's LISTLOG and LISTUSERS reports, and
     on VEAUDIT reports.


MPEXQEDITFILE_117
MPEXQEDITFILE
   * MPEXQEDITFILE [STR]

     If you use MPEX's %QEDIT command (which executes an operation on a fileset
     using Robelle's popular QEDIT text editor), MPEX will try to run
     QEDIT.PUB.ROBELLE.  If you've moved QEDIT out of PUB.ROBELLE, you can set
     the MPEXQEDITFILE variable to point to wherever QEDIT may be, e.g.

   %SETVAR MPEXQEDITFILE "QEDIT.PUB.UTIL"


MPEXDBADGFILE_118
MPEXDBADGFILE
   * MPEXDBADGFILE [STR]

     If you use MPEX's %DBADGALT command (which alters IMAGE database capacity
     on a fileset using the popular ADAGER program), MPEX will try to run
     ADAGER.PUB.REGO.  If you've moved ADAGER to some other group.account, you
     can set the MPEXDBADGFILE variable to point to wherever ADAGER may be,
     e.g.

   %SETVAR MPEXDBADGFILE "ADAGER.PUB.TOOLS"


MPEXDBGENFILE_119
MPEXDBGENFILE
   * MPEXDBGENFILE [STR]

     If you use MPEX's %DBGENALT command (which alters IMAGE database capacity
     on a fileset using the BRADMARK's popular DBGENERAL program), MPEX will
     try to run DBGENRL.PUB.BRADMARK.  If you've moved DBGENERAL to some other
     group.account, you can set the MPEXDBGENFILE variable to point to wherever
     DBGENERAL may be, e.g.

   %SETVAR MPEXDBGENFILE "DBGENRL.PUB.TOOLS"


MPEXDBMGRFILE_120
MPEXDBMGRFILE
   * MPEXDBMGRFILE [STR]

     If you use MPEX's %DBMGRALT command (which alters IMAGE database capacity
     on a fileset using DISC's popular DBMGR program), MPEX will try to run
     DBMGR.PUB.DISC.  If you've moved DBMGR to some other group.account, you
     can set the MPEXDBMGRFILE variable to point to wherever DBMGR may be, e.g.

   %SETVAR MPEXDBMGRFILE "DBMGR.PUB.TOOLS"


MPEXTELLBACK_121
MPEXTELLBACK
   * MPEXTELLBACK [STR]

     Tells MPEX who to inform when MPEX-created jobs (created with $, %SUBMIT,
     or %SCHEDULE) complete (or encounter errors).

     Setting this variable to "!!HPJOBNAME,!!HPUSER.!!HPACCOUNT" makes MPEX
     jobs send the message to all sessions logged on with your job/session
     name, your user ID, and your account name.  Setting it to "#S!!HPJOBNUM"
     (the default) makes MPEX jobs send the message to your session
     specifically (if you log off and log back on, no message will arrive).

     If you want to, you can set this variable to anything you please -- you
     might set it to "MANAGER.SYS" to make all jobs send messages to
     MANAGER.SYS, or what have you.


MPEXTELLBACKCMD_122
MPEXTELLBACKCMD
   * MPEXTELLBACKCMD [STR]

     Normally, MPEX does a :TELL to notify you when your MPEX-created jobs
     (created with $, %SUBMIT, or %SCHEDULE) finish or encounter errors.  You
     may use this variable if you would prefer a :TELLOP, %WARNF, or even have
     MPEX execute your own command file by setting it to something like "XEQ
     MYCMD".


MPEXPREFIXDEFnn_123
MPEXPREFIXDEFnn
   * MPEXPREFIXDEFnn [STR]

     "nn" is the ASCII code for any character (except for the reserved
     characters "%", "!", "?", "$", ":", and ",").  Setting one of the
     variables lets you redefine special characters so that, when they are used
     as the first character of an MPEX command, they are replaced with a
     string.  This feature is used primarily for "%SPOONFEEDing" (see
     %SPOONFEED in the commands reference section), but another useful example
     is

   %SETVAR MPEXPREFIXDEF![ORD('=')] "CALC "

which allows you to say things like

   %=52*40
   %=TODAY+30
   %=VEFINFO("FOOBAR").CREDATE
   etc.


MPEXALARMPREFIX_124
MPEXALARMPREFIX
   * MPEXALARMPREFIX [STR]

     Set this variable to a string that you want prefixed to all %ALARM
     messages you set.


MPEXWARNFPREFIX_125
MPEXWARNFPREFIX
   * MPEXWARNFPREFIX [STR]

     Set this variable to a string that you want prefixed to all %WARNF
     messages you send.


VESOFTDEFAULTxxx_126
VESOFTDEFAULTxxx
   * VESOFTDEFAULTxxx [STR]

     A group of variables that set defaults for certain MPEX commands.  For
      more information, see
     "Setting Default PARMS For MPEX Commands" in the Running MPEX section.


VECURRFILENAME_127
VECURRFILENAME
   * VECURRFILENAME [STR] (read-only)

     This variable contains the name of the currently executing  command file
     (in MPEX), job stream or ::USE file (in STREAMX), or menu file (in a
     SECURITY/3000 menu).

MPE FILENAMES


Filesets__Standard_MPE_filenames__128
Filesets: Standard MPE filenames

Syntax:   filename [/lockword][.groupname [.accountname]]

Examples: MYFILE
          JAN93.DATA
          MAINPROG.SOURCE.DEVELOP
          LOCKED/TIGHT.DATA.PROD

Nearly all MPEX commands deal with files and filenames in some manner, so a
basic understanding of what defines a filename is needed in order to utilize
our software in the best possible manner.  Detailed information on files and
filenames can be found in HP's manuals, so our discussion here will be very
brief.

An MPE filename consists of a file, group, and account name.  The file, group,
and account names MUST begin with a letter and are followed by up to 7 letters
or digits.  No special characters are allowed, and the "."(dot) character is
used to separate the group and account names.  The group and account are
optional, and if not specified, will default to the user's logon group and
account.  Although you may use upper or lowercase letters, MPE translates all
lowercase letters to uppercase letters for an MPE filename.

Lockwords are passwords to use the file.  If you do not specify the lockword of
the file when referring to the file (such as when TEXTing in a source file in
EDITOR), the operating system will prompt you for the lockword.  If you do not
enter the correct lockword, then access to the file will be denied.

MPE FILESETS


Filesets__Standard_MPE_filesets__129
Filesets: Standard MPE filesets

Syntax:   filespec [.groupspec [.accountspec]]

Examples: @.@.@
          @.@.ACCOUNT
          ??@.GROUP.ACCOUNT
          K#######.VER@.DOCUMENT
          @ABC@.@DEF@

An MPE fileset is a simply an MPE filename with optional wildcard characters
(note that the LOCKWORD of the file is not specified for a fileset).  The
wildcard characters that may be specified are as follows:

  character what it means

    @       zero or more characters, either letters or digits

    ?       Exactly one character, either a letter or a digit

    #       Exactly one digit

[ ... ]      Exactly one character taken from the set of characters given
            between the square brackets.  For example, "[123ASDF]" means any
            one of the characters "1", "2", "3", "A", "S", "D" or "F".  A
            character range can be specified using the "-" (hyphen) character,
            i.e.  "[A-C]" means either the letter "A", "B", or "C".  Of course,
            these two can be combined, so "[A-HO-Z]" means any letter except I,
            J, K, L, M, or N.

POSIX FILENAMES


Filesets__Enhanced_POSIX_Filenames__130
Filesets: Enhanced POSIX Filenames

Syntax:   .[/]posixfilename
          /posixfilename

Examples: .MYFILE
          .myfile
          /accounting/93_04_22_datafile
          ./subdir/ACTUAL_filename
          /a_posix_file/with_a_very_long.but_still-legal.filename
          /MPEACCT/MPEGROUP/MPEFILE

With the introduction of version 4.5 of the MPE/iX operating system, you are
allowed to specify files using what is known as HFS syntax.  "HFS" stands for
"Hierarchical File System" and is often referred to as "POSIX", although
"POSIX", as such, actually encompasses a lot more than the way you specify
filenames.  In this manual, you may see references to either HFS or POSIX, you
can consider them the same unless noted otherwise.  Of course, if you are not
using a system that supports POSIX, then you cannot specify files using HFS
syntax.

A POSIX filename, unlike an MPE filename:

  *  may contain upper AND lowercase letters (which are significant, /FILE is
     not the same as /file).
  *  may contain these special characters: "-" (hyphen), "_" (underscore), and
     "." (dot).
  *  may begin with any character except "-", which allows digits, ".", and the
     "_".
  *  may be up to 16 characters in length if the file is built in the root
     directory (beginning with just "/") or if is it built in any MPE group
     (usually anything beginning with "./" if you have not changed your current
     working directory to a POSIX directory).
  *  may be up to 255 characters in length if the file is built anywhere else.
  *  can not have a lockword since the "/" character is used to delimit
     subdirectories.

Since MPE filenames are always in uppercase, MPE will automatically upshift any
filename beginning with a letter from "a" to "z".  In order to specify a POSIX
filename to MPEX or any other MPE utility, the filename is prefaced with either
a period, a forward slash, or both.  POSIX files that begin with the forward
slash character (/) are considered to be in the root directory, files that
begin with a period (.) are in your current directory, and files that begin
with two periods and a forward slash (../) are in your parent directory.
Forward slashes in the rest of a POSIX filename are used to delimit
subdirectories, which are logically equivalent to MPE groups in an MPE account.
(In fact, files in the MPE directory can be referred to using POSIX notation as
shown in the last example.)

POSIX FILESETS


Filesets__Enhanced_POSIX_Filesets__131
Filesets: Enhanced POSIX Filesets

A POSIX fileset, like an MPE fileset, is an explicit filename that may contain
wildcard characters.  In MPE, POSIX filesets ending with a forward slash will
include subdirectories recursively, so the POSIX fileset of "/" is equivalent
to "@.@.@" for MPE files.  POSIX filesets ending with an "@" character will not
search any subdirectories for files, so the POSIX fileset of "/@" is the list
of files, directories, and accounts that are ONLY in the root directory.

The same wildcard rules apply for POSIX filesets as for MPE filesets with one
notable exception.  Since the "-" character is a legal character in a filename,
and when specifying a range of characters such as "[I-N]" you have to use the
"-" character as part of the syntax and not a legal character, it would seem
impossible to specify a "-" character in a "[...]" range set.  As it turns out,
if the "-" character is the first or last character in a range set, then it is
treated as "one of the characters to allow" instead of indicating "a range of
characters to allow".  For example, to indicate that any letter from "I" to "N"
OR the "-" character may be used, you can specify this range set as follows:

   [-I-N]  or  [I-N-]

MPEX FILESETS


Filesets__General_MPE_and_POSIX_filesets_132
Filesets: General MPE and POSIX filesets

Syntax:   mpefileset [+|- mpefileset] [...  ] [(selectioncondition)]
          posixfileset [+|- posixfileset] [ ...  ] [(selectioncondition)]
          eitherfileset [+|- eitherfileset] [ ...  ] [(selectioncondition)]

Examples: @.@.MYACCT
          /posixdir/mydir/(SECTORS>1023)
          @.@.SYS + @.@.TELESUP
          /SYS/ + @.@.TELESUP - /@/PUB/@/
          @.@.@(SAVABLESECTORS>100)

          @.MYGROUP.MYACCT (ISHIDDEN)

          @.@.@-@.PUB.SYS-@.@.VESOFT(ACCDATE<TODAY-120 and NOT ISPRIV)
          / - /SYS/ -/VESOFT/(ACCDATE<TODAY-120 and NOT ISPRIV) (POSIX)

POSIX note: Some of the examples in this manual will show an example of a
            normal MPE fileset and an example of an equivalent POSIX fileset
            (or a mixture of the two).  The POSIX example will be marked with
            (POSIX) as shown above.  Users of MPE/iX systems without POSIX
            support should refer to the original MPE syntax shown.

One of the most important features of MPEX -- probably the most important -- is
its ability to work on filesets.  You can compile filesets, edit them, copy
them, purge them, rename them, print them, etc.

However, the filesets MPEX can operate on aren't just ordinary MPE or POSIX
filesets.  They are a vastly enhanced superset of MPE and POSIX filesets, which
includes features like:

   * The ability to specify several filesets in one command, e.g.

      %PURGE K#######.@.@ + LOG####.PUB.SYS
      %PURGE K#######.@.@ + /SYS/PUB/LOG####     (POSIX)

    The "+" sign means "use all files in fileset 1 and all files in fileset 2".
    On systems that support POSIX, MPE filesets and POSIX filesets may be
    intermixed in the same command.

   * The ability to exclude filesets, e.g.

      %COPY @.DATA+@.SOURCE - MYDB@.DATA - COPY@.SOURCE, @.@.NEWDEV
      %COPY ../DATA/+../SOURCE/ - ../DATA/MYDB@ - ../SOURCE/COPY@,&
            @.@.NEWDEV   (POSIX)

    The "-" sign means "use all files in the + filesets except for those files
    after the - ".

POSIX note: Since the "-" character may be used as part of a POSIX filename,
            there must be a leading space before the "-" character if the
            preceding fileset is a POSIX fileset.  You may find it convenient
            to get into the habit of always inserting spaces around the "-"
            character in a fileset.

  * The ability to select files by their file code, their last access date, the
    disc space they use, etc.  -- by virtually any file attribute you can think
    of.  (This "selectioncondition" is a boolean expression; please see
    Appendix for more details on expressions.) For instance,

 %PURGE @.@.@ - @.@.VESOFT(ACCDATE<TODAY-120 and NOT ISPRIV)
 %PURGE /     - /VESOFT/ (ACCDATE<TODAY-120 and NOT ISPRIV) (POSIX)

    will purge all the files in the system (except those in the VESOFT account)
    that haven't been accessed in the last 120 days and have a filecode that's
    not "PRIV".  Other examples of this extraordinarily powerful feature
    include:

      %LISTF @.@(ONDEVICE(1)), 4

    which finds all the files that are at least partially on disc device 1,
    and:

      %LISTF @.@.@(ISPRIV and (DBSETTYPE="A" or DBSETTYPE="M")
                  and DBSETFULLNESS>.75),DB

    which shows information on all the IMAGE Automatic or Manual master
    datasets (DBSETTYPE="A" or DBSETTYPE="M") that are more than 75% full
    (DBSETFULLNESS>.75).

      %LISTF @.MYGROUP.MYACCT (ISHIDDEN), 2


ISHIDDEN_133
ISHIDDEN
    The ISHIDDEN attribute will select only those files that are "hidden" from
    MPE's :LISTF output.  Files that are "hidden" are files that begin with
    either a "/" or "." and contain characters that cannot be used in an MPE
    filename.  (in other words, all of the files that can ONLY be specified
    using HFS notation.) This would include files that have more than 8
    characters in the filename, contain lowercase letters or the "_","-", or
    "." characters, or reside in a SUBDIRECTORY instead of a GROUP.  Remember,
    MPEX's %LISTF mode 2 will display all MPE and HFS named files that qualify,
    even if only given an MPE fileset.  Some attributes that are only available
    on POSIX systems, such as BYTE STREAM files, can still have MPE-compliant
    names and therefore will not be "hidden" files.

+ FILESETS


__Filesets__134
+ Filesets

"+ filesets" -- filesets that are combined using the + operator are quite
straightforward.  A command such as

   %PURGE K#######.@.@ + LOG####.PUB.SYS

simply operates on all the files in the first fileset (in this case, all
EDITOR's K-files in the system) and on all the files in the second fileset (in
this case, all the system log files).  Other examples might include

   %PRINT AP010.SOURCE + AP030.SOURCE + AP175.SOURCE + AP250.SOURCE; &
          OUT=*LP; PAGEHEAD

(which simply saves you having to type four separate %PRINT commands), or

   %EDIT AP@.SOURCE + GL@.SOURCE, SET VARIABLE;LIST 1/2

which performs the given EDITOR command(s) on all the files in the SOURCE group
that start with AP or GL.

The operations on the files are performed one fileset at a time, each fileset
in its own internal order.  In other words, if you say

   %LISTF @.SOURCE+@.DEV, 3

then the SOURCE files will be output first and the DEV files after them (even
though the files within each fileset will be output in alphabetical order).

Similarly, if a file is included in more than one of the "+"ed filesets, it'll
be processed each time it appears.

- FILESETS


__Filesets__135
- Filesets

"- filesets" allow you to EXCLUDE files from an MPEX fileset.  For instance,

   %COPY @.DATA+@.SOURCE - MYDB@.DATA - COPY@.SOURCE, =.=.NEWDEV

will copy into the NEWDEV account all the DATA and SOURCE group files
(@.DATA+@.SOURCE) EXCEPT for those in the filesets MYDB@.DATA and COPY@.SOURCE.

Note that - filesets apply to the ENTIRE MPEX fileset, not just to the +
fileset immediately preceding.  For instance, if you say

   %LISTF A@+B@-@X-@Y

then ALL files that end with X or Y will be excluded (the "-@X-@Y" applies to
"A@+B@", not just to B@).

INDIRECT FILES


Indirect_Files__136
Indirect Files


__137
!


__138
^


__139
*

MPEX lets you select files by their filenames (with wildcards, + filesets, and
- filesets) and by various other attributes.  What if, however, you want to
operate on a list of files whose names don't necessarily have much in common?

For instance, say that the source files for one of your programs are stored in
the files MAINLINE.SOURCE.AP, UTILSUBS.SOURCE.AP, XFILE.INCLUDE.AP, and
DECLS.SOURCE.AP.  You might want to be able to compile them all, edit them all,
copy them all, etc., without having to specify the fileset MAINLINE.SOURCE.AP +
UTILSUBS.SOURCE.AP + XFILE.INCLUDE.AP + DECLS.SOURCE.AP on each %COBOL, %EDIT,
%COPY, etc.  command (imagine what the fileset would look like if these weren't
just four files, but 40 or 400!).

Instead, you can build an editor file that contains 4 lines:

   MAINLINE.SOURCE.AP
   UTILSUBS.SOURCE.AP
   XFILE.INCLUDE.AP
   DECLS.SOURCE.AP

Say that you call this file FILELIST.SOURCE.AP; you could now say

   %COBOL ^FILELIST.SOURCE.AP (MODDATE>TODAY-3), MYPROG

or

   %PRINT ^FILELIST.SOURCE.AP;OUT=*LP;PAGEHEAD

or

   %EDITCHG ^FILELIST.SOURCE.AP, "ITEM-NO", "ITEM-NUMBER"

Note the "^" before "FILELIST.SOURCE.AP".  This tells MPEX that this command
(%COBOL, %PRINT, %EDIT, or whatever) should not be executed on the file
FILELIST.SOURCE.AP itself (which is what would happen if you'd omitted the
"^").  Instead, it should be executed on the files listed in the file
FILELIST.SOURCE.AP.

This "indirect file" can contain either filenames or filesets; it might, for
instance, say:

   MAINLINE.SOURCE.AP
   UTILSUBS.SOURCE.AP
   X@.INCLUDE.AP
   DECLS.SOURCE.AP

which means that it includes the three explicitly specified files (MAINLINE,
UTILSUBS, and DECLS) but also all the files in the fileset X@.INCLUDE.AP.  In
general, you should think of an indirect file as just a single MPEX fileset
with all the component files "+"ed together.

Each line of this file may be a filename or fileset, with @, #, or ? wildcards
and [...] range sets.  On systems that support POSIX filenames, POSIX filesets
may be included as well (in fact, both types of filesets may be in the file at
the same time).  However, it may not include "+"s, "-"s (except as part of a
POSIX filename), or selection criteria -- features which are not normally
present in ordinary MPE filesets.

You may also specify an indirect file as a "-" fileset, e.g.

   %PURGE @.SOURCE-^FILELIST.SOURCE.AP

This is the same thing as specifying each line in the FILELIST file as a
separate "-" fileset on the %PURGE command, i.e.

   %PURGE @.SOURCE-MAINLINE.SOURCE.AP-UTILSUBS.SOURCE.AP-
            X@.INCLUDE.AP-DECLS.SOURCE.AP

Note: although you can have many hundreds of lines in an indirect fileset used
for "+" purposes, you can have only up to about 80 lines in an indirect fileset
being "-"d (the exact maximum depends on the length of each line).


__140
#
If you like, you can include comments in indirect files by putting a "#" in
column one (this feature was added for compatibility with the MPE/iX Link
Editor).  For example:

   #This indirect file lists all of the NMOBJ files that need to be
   #included in the production RL.
   LIB1OBJ
   LIB2OBJ
   LIB3OBJ
   LIB4OBJ
   LIB5OBJ

SELECTION CRITERIA


Selection_criteria__introduction__141
Selection criteria: introduction

Probably the most useful aspect of MPEX filesets is the ability to select files
based on some file attribute(s).  For instance, you might say:

 %PURGE @.@.@ - @.@.VESOFT(ACCDATE<TODAY-120 and NOT ISPRIV)
 %PURGE /     - /VESOFT/ (ACCDATE<TODAY-120 and NOT ISPRIV) (POSIX)

to purge all the files that match the selection criteria

   ACCDATE<TODAY-120 and NOT ISPRIV

(i.e.  they haven't been accessed in 120 days AND their filecodes are not
"PRIV").  Other excellent examples include:

   %LISTF @.@.@ - @.@.VESOFT&
            - @.PUB.SYS(ISPROG and PROG.PMCAP),5

   %LISTF / - /VESOFT/&
            - @.PUB.SYS(ISPROG and PROG.PMCAP),5  (POSIX)

      which finds all the program files that have PM capability (PROG.PMCAP)
      except those that are in the VESOFT account or in the PUB.SYS group.

   %ALTFILE @.@(CREATOR="JOHN"); CREATOR=MANAGER

      which changes to MANAGER the creator ID of all the files in the logon
      account that were created by JOHN (CREATOR="JOHN").

   %LISTF CUST?#.DB(DBSETTYPE<>"D" and DBSETFULLNESS>.65),DB

      which shows all the CUST database datasets (CUST?#.DB) that are not
      details (DBSETTYPE<>"D") and are more than 65% full (DBSETFULLNESS>.65).

   %ALTFILE @.DATA(DEVICESECTORS(1)>=SECTORS/10); DEV=2

      which moves to device 2 all the DATA files that have at least 1/10th of
      their disc space on device 1.

As you can see, the selection criteria can be arbitrary MPEX expressions,
involving:

   * File attribute variables and file attribute functions, which contain
     information about the current file.

     For instance,

        - CREATOR is a string variable containing the file's creator ID;

        - ACCDATE is a date variable containing the file's last access date;

        - SECTORS is an integer variable containing the number of disc sectors
          the file occupies;

        - PROG.PMCAP is a boolean (TRUE/FALSE) variable that's true if the
          current program file has PM capability;

        - ONDEVICE(ldev) is a function that returns TRUE if at least one extent
          of the current file is located on the specified LDEV;

     Note that these variables and functions refer to attributes of the current
     file being processed (the file for which selection criteria are being
     checked).  This should be distinguished from ordinary MPEX variables (set
     with %SETVAR) or operators/functions (like +, -, UPS, STR, etc.) that
     don't care about what the current file is.

   * Standard MPEX variables, operators, and functions, such as +, -, AND, OR,
     HPUSER, HPGROUP, etc.  These are all discussed in Appendix, and are the
     same in selection conditions, in the %IF statement, in the %CALC command,
     etc.

With all the operators and file attribute variables that are defined, you can
select files on virtually any basis you can think of.

FILE RANGES


File_ranges__142
File ranges


fileset_wildcards____143
fileset wildcards: ?
What if you want to find all the files whose filenames are in a range; e.g.
all the files that start with "K" through "P" in the DATA group? Well, you
could say %LISTF K@.DATA + L@.DATA + M@.DATA + N@.DATA + O@.DATA + P@.DATA but
(of course) there is an easier way.


______144
[...]
In addition to the old MPE wildcards @, ?, and #, MPEX on both MPE/V and MPE/iX
supports a file range wildcard, best described by example:

   [ABC]           exactly one character, an A, B, or C
   [A-M]           exactly one character, an A, B, C, ..., L, or M
   [A-EP-SZ]       exactly one character, an A, B, C, D, E, P, Q, R, S, or Z
   [A-M]@          any number of characters that start with an A through M
   @[05]@          any number of characters that contain a 0 or a 5
   ...  and so on

As you see, a "[...]" construct matches exactly one character, which must be
one of the ones listed inside the brackets; saying "[x-y]" indicates a range of
characters, and several ranges and/or single characters may be included in one
"[...]" construct.  So, for the example above, you would use the following
command:

   %LISTF [K-P]@.DATA

POSIX note: Since the "-" character is a legal character in a filename, but in
            the above syntax a "-" indicates a range of characters, it would
            seem impossible to indicate that a "-" is simply "one of the
            allowed characters".  However, if the "-" is the first or last
            character in the set, then it means that the "-" character is one
            of the allowable characters and not an indication of a range of
            allowable characters.

POSIX note: Since POSIX filesets are case sensitive, [a-z] is not the same as
            [A-Z].  To select a single alphabetic character, without regard to
            case, use [a-zA-Z]

This new syntax makes it easy for patterns you enter as parts of filesets,
usersets, and MPE account-/user-/group-sets to exceed 8 characters; therefore,
we've increased the maximum length of any part of such an object (i.e.  the
file, group, or account part of a fileset), when used as part of a pattern, to
16 characters.

What if you want to find all the files whose filenames are in a range like
AP050 through AP230? This is a commonly asked-for feature, and one that
ordinary MPE wildcards can't handle (AP@ refers to all files that start with
AP, and AP[0-2]@ isn't quite right, either, since it would include filenames
like AP023 and AP256 -- you just want those from AP050 to AP230).

MPEX's powerful selection conditions do the trick.  Just say:


BETWEEN_145
BETWEEN

   %PRINT @(BETWEEN(FILE,"AP050","AP230"))

This selects all the files in your group (@) whose filenames (the file
attribute variable FILE) are between "AP050" and "AP230".  The BETWEEN function
(documented in Appendix) will, in general, check to see if the value of its
first parameter is between the values of its second and third parameters; file
ranges are just a special case.

Of course, you can do this for any command, not just %PRINT; also, in this
command you could have said

   %PRINT AP@(BETWEEN(FILE,"AP050","AP230"))

since all the files you want are also in the fileset AP@.

TARGET FILESETS


Target_filesets__146
Target filesets

The filesets we've just been describing -- the ones with +'s, -'s, and
selection criteria -- are called "SOURCE FILESETS", filesets that can be
specified as the first parameter of a fileset-handling command.  A TARGET
fileset is a fileset that is specified as the second or last parameter of a
fileset-handling command.  For instance, you might say

   %COPY @.SOURCE(ACCDATE>=TODAY-2),@.CHANGED

in which case @.SOURCE(ACCDATE>=TODAY-2) is the source fileset, and @.CHANGED
is the target.

What if you were to type this instead:

   %COPY @.SOURCE, @.CHANGED-X@.CHANGED(ACCDATE>=TODAY-2)

Does this make any sense? Not really.  The second parameter -- the "target" of
the %COPY command -- doesn't specify which files are to be copied, but rather
what the new names of the copied files will be.  What does it mean when we put
an "(ACCDATE>=TODAY-2)" selection condition on the target fileset? The object
files need not even exist (they probably don't) -- how can we select based on
their last access date? And what about the "-X@.CHANGED" -- what if one of the
files in SOURCE starts with X? If we can't copy it into a file that starts with
X in the CHANGED group, what could we do?

What this all means is that + filesets, - filesets, and selection conditions
work only on source filesets (the first fileset on each fileset-handling
command).  Target filesets, with one minor exception, must be simple MPE or HFS
style filesets.


__147
=
The exception for target filesets is the "=" wildcard character.  Say that you
type

   %COPY AP@.SOURCE+GL@.SOURCE, =.BACKUP

The "=" sign means "make the filename of the target file be the same as the
filename of the source file".  (If you'd put the "=" in the group, account, or
lockword position, it would make the group,account and lockword of the target
be the same as the group,account and lockword of the source.)

How is an "=" different from an "@"? Well, "=" refers to the ENTIRE source file
part (or group or account) -- "@" refers only to that part which corresponds to
an "@" in the source fileset.  In other words, saying

   %COPY S@.DEV.AP, B@.DEV.AP

will copy the file STEST.DEV.AP into the file BTEST.DEV.AP -- the "@" in the
target fileset was replaced by "TEST".  Saying

   %COPY S@.DEV.AP, B=.DEV.AP

will copy the file STEST.DEV.AP into the file BSTEST.DEV.AP -- the "=" in the
target fileset was replaced by "STEST", the entire file portion of the source
file name.

"=" is most useful in cases like those shown in the first example:

   %COPY AP@.SOURCE+GL@.SOURCE, =.BACKUP

Here, the target filename is defined to be the SAME as the source filename,
regardless of which fileset (AP@.SOURCE or GL@.SOURCE) the source file came
from.  If the source fileset didn't have a "+", e.g.

   %COPY AP@.SOURCE, =.BACKUP

then we could easily do the same thing without an "=":

   %COPY AP@.SOURCE, AP@.BACKUP

Another important application of "=" is to preserve file lockwords on a %COPY,
%FCOPY, or %RENAME:

   %COPY @.SOURCE, @/=.BACKUP

The "=" in the lockword part of the target fileset means that the target file
should be built with the same lockword (if any) as the source file.  Otherwise,
if you don't specify a lockword, MPEX will assume (just like MPE) that the
target file should be unlockworded.

POSIX NOTE: SOURCE AND TARGET FILESETS USING HFS SYNTAX


SOURCE_and_TARGET_filesets_using_HFS_syntax__148
SOURCE and TARGET filesets using HFS syntax


HFS_filesets_and_the_____character_149
HFS filesets and the "/" character


HFS_filesets_and_the_____character_150
HFS filesets and the "-" character
On systems that support POSIX, certain changes have to be made for special
characters in a source or target fileset.  For instance, we have already
mentioned that the "/" character is used to delimit directories and
subdirectories and therefore cannot be used to indicate a lockword in a POSIX
fileset.  Likewise, since the "-" character is a legal character in filenames,
(but not as the first character of a filename), you must insert a space before
a file or fileset that is to be subtracted if the previous file is specified
using HFS syntax.


HFS_filesets_and_the_____character_151
HFS filesets and the "@" character


HFS_filesets_and_the_____character_152
HFS filesets and the "=" character
The "@" character still means "zero or more characters", but it will not go
beyond a "/" character (which, in this case, is the same as the "." character
used to separate the file, group, and account parts of an MPE filename).  Like
the "@", the "=" character in a target fileset will replace the current element
with the complete corresponding element from the source fileset.  This is fine
in most cases, but could be a bit tedious if you are renaming or copying a file
that is several directory levels deep.  In this case, the shorthand notation of
"==" in a TARGET fileset means "use the same path as the source" (see below for
an example).

While the standard wildcard characters will let you specify nearly any fileset
that you are likely to ever use, there are still some filesets that cannot be
specified easily.  For instance, the fileset:

     /A@/B@/C@

is fairly straightforward -- it selects any file that begins with the letter
"C", residing in any subdirectory beginning with a "B", located in any
directory beginning with an "A".  However, the file:

     /ARIZONA/BUSINESS/TAXES/COLLECTIONS

will not qualify since "COLLECTIONS" is in the fourth level while "/A@/B@/C@"
only has three levels.


___153
//
In order to select files in any sub-level, you can use "//" to mean "any number
of directories and subdirectories".  So, in order to qualify "COLLECTIONS" in
the above example, use:

     /A@/B@//C@

However, the "//" may not be followed by another "/", or in other words, the
only thing that can follow a "//" is a wild-carded FILE specification, not a
wild-carded DIRECTORY specification.


__154
/
In both of these examples, the last element of the source fileset was "C@",
which will only select files and directories that start with "C" in the
directory specified.  If the last character of a POSIX source fileset is a "/",
then MPEX will include all the files in each subdirectory that matches the last
directory level specified.  For example, let's say you have a directory called
"/source", with several subdirectories of "project-01", "project-02", and so
on.  In each "project-##" directory, the actual source code, "include" files,
libraries, notes, and any other related files are stored in one or more
subdirectories.  In order to specify "everything related to project 11", you
could use the fileset:

     /source/project-11/

To specify all files for all projects, you would use:

     /source/project-@/


___155
==


HFS_filesets_with_______156
HFS filesets with "=="
Since an HFS pathname can contain several levels, it could be a bit tedious to
have to type  "/=/=/=/=/=/=/=/NEWTARGETNAME" when renaming or copying files
within the same directory, so for POSIX target filesets, the shorthand notation
of "==" means "the same path as the source".  For example, to rename a file
that is buried several levels deep (keeping the file in the same directory) the
following syntax can be used:

     %RENAME /level1/level2/level3/level4/level5/filename, ==/newfilename


TARGET_filesets_157
TARGET filesets
If the TARGET of a copy or rename operation is a directory, then all the files
from the source fileset are copied or renamed into the directory (This is
similar to other operating systems such as UNIX or MS-DOS).


File_attributes__158
File attributes


Selection_criteria__for_files_159
Selection criteria: for files
As we mentioned before, a selection criterion is an expression that can include
some FILE ATTRIBUTE VARIABLES AND FUNCTIONS that contain information about the
current file.

In general, whenever MPEX operates on a fileset, it makes these file attribute
variables/functions available to you so that you can make decisions based on
the attributes of the current file.  This includes:

   * Selection criteria,

   * %LISTF command flexible template files,

   * the VEFINFO(...).attrvar function, and

   * %REPEAT/%FORFILES statements, in which you can refer to file attribute
     variables and functions by using the ![xxx] variable syntax and prefixing
     each file attribute variable name with "RFILE." -- e.g.


RFILE__160
RFILE.

        %REPEAT
        %>FILE MYINFILE=!MPEXCURRENTFILE
        %>RUN MYPROG;INFO="![RFILE.CREATOR]";PARM=![RFILE.INTCODE]
        %>FORFILES @.DATA

Each file attribute variable -- like all MPEX variables -- has a data type
(INTEGER, STRING, or BOOLEAN).  Unlike MPEX variables but like some MPEX
operators (see Appendix), some attribute variables might also be of type DATE
or type TIME.

It's important to know the variable's type because the type controls what
operators you can use on the variable -- for instance, if you say %LISTF
@.@.@(ACCDATE<CODE),3 you'll get an error -- ACCDATE is of type DATE, CODE is
of type STRING, and you can't compare dates and strings.  On the other hand,

   %LISTF @.@.@(ACCDATE<TODAY-120),3

is quite valid:

   * ACCDATE is a file attribute variable of type DATE.

   * TODAY is an MPEX function (see Appendix) of type DATE.

   * The - operator can take a date (TODAY) and an integer (120), and will
     return another date.

   * Finally, you'll be comparing ACCDATE (a date) against TODAY-120 (also a
     date), which is perfectly legal.

With all that said, here are the file attribute variables and file attribute
functions that MPEX defines.

   * Remember, you can use them directly in selection criteria and %LISTF
     template files -- in %REPEAT ...  %FORFILES constructs they have to be
     prefixed with "RFILE.".

   * Also remember that all of these attribute variables/functions apply to THE
     FILE BEING CURRENTLY PROCESSED.  Thus, when we say that "ACCOUNT" refers
     to "Account name", we mean the account name of the current file.

   * Each variable is marked [STR] if it's a string, [INT] if an integer,
     [BOOL] for boolean, [DATE] for date, [TIME] for time, and [REAL] for real.

   * [STR] variables always have trailing blanks removed.

   * For your convenience, the file attribute functions and variables are
     roughly categorized by the LISTF mode (if any) that shows them -- all the
     things shown by %LISTF ,2 first, then those shown by %LISTF ,XL3, etc.  Of
     course, each file attribute can be used in any MPEX command, not just
     %LISTF.


Selection_criteria__for_normal_files_161
Selection criteria: for normal files

%:LISTF MYFILE.PUB.SYS,2
ACCOUNT=  SYS         GROUP=  PUB

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

MYFILE  * EDTCT    80B  FA       14100      18901  32     5930 27 29


FILE_162
FILE
FILE          [STR]   Filename                                here "MYFILE"


GROUP_163
GROUP
GROUP         [STR]   Group name                              here "PUB"


ACCOUNT_164
ACCOUNT
ACCOUNT       [STR]   Account name                            here "SYS"


OPENED_165
OPENED
OPENED        [BOOL]  TRUE if file currently FOPENed;         here TRUE


FMTOPENED_166
FMTOPENED
FMTOPENED     [STR]   "*" if FOPENed, " " if not              here "*"


INTCODE_167
INTCODE
INTCODE       [INT]   Filecode as an integer                  here 1052


CODE_168
CODE
CODE          [STR]   Filecode as a string                    here "EDTCT"


RECSIZE_169
RECSIZE
RECSIZE       [INT]   Record size in bytes                    here 80


FMTRECSIZE_170
FMTRECSIZE
FMTRECSIZE    [STR]   Record size                             here 80B
                      includes "W" if size is in Words, "B" for Bytes.


FMTTYPE_171
FMTTYPE
FMTTYPE       [STR]   File type                               here "FA"


EOF_172
EOF
EOF           [INT]   Number of records in file               here 14100


FLIMIT_173
FLIMIT
FLIMIT        [INT]   File limit                              here 18901


BLOCKFACTOR_174
BLOCKFACTOR
BLOCKFACTOR   [INT]   Blocking factor                         here 32


BLOCKSIZE_175
BLOCKSIZE
BLOCKSIZE     [INT]   Block size, in bytes                    here 2560 (80*32)


SECTORS_176
SECTORS


Disc_space__selecting_by_used_space_177
Disc space: selecting by used space
SECTORS       [INT]   # of sectors used by file               here 5930


NUMEXTENTS_178
NUMEXTENTS
NUMEXTENTS    [INT]   Current number of extents               here 27


MAXEXTENTS_179
MAXEXTENTS
MAXEXTENTS    [INT]   Maximum number of extents               here 29


ISFIXED_180
ISFIXED
ISFIXED       [BOOL]  TRUE if fixed-length records            here TRUE


ISVARIABLE_181
ISVARIABLE
ISVARIABLE    [BOOL]  TRUE if variable records                here FALSE


ISUNDEFINED_182
ISUNDEFINED
ISUNDEFINED   [BOOL]  TRUE if undefined records               here FALSE


ISASCII_183
ISASCII
ISASCII       [BOOL]  TRUE if file is ASCII                   here TRUE


ISBINARY_184
ISBINARY
ISBINARY      [BOOL]  TRUE if file is BINARY                  here FALSE


ISCCTL_185
ISCCTL
ISCCTL        [BOOL]  TRUE if file has CCTL                   here FALSE


ISNOCCTL_186
ISNOCCTL
ISNOCCTL      [BOOL]  TRUE if file has NOCCTL                 here TRUE


ISSTD_187
ISSTD
ISSTD         [BOOL]  TRUE if not MSG/CIR/RIO/KSAM file       here TRUE


ISRIO_188
ISRIO
ISRIO         [BOOL]  TRUE if type RIO file                   here FALSE


ISKSAM_189
ISKSAM
ISKSAM        [BOOL]  TRUE if KSAM (or KSAMXL) key/data file  here FALSE


ISKSAMXL_190
ISKSAMXL
ISKSAMXL      [BOOL]  TRUE if KSAMXL file                     here FALSE


ISMSG_191
ISMSG
ISMSG         [BOOL]  TRUE if MSG file                        here FALSE


ISCIR_192
ISCIR
ISCIR         [BOOL]  TRUE if CIR file                        here FALSE


ISCMPROG_193
ISCMPROG
ISCMPROG      [BOOL]  TRUE for PROG files only                here FALSE


ISNMPROG_194
ISNMPROG
ISNMPROG      [BOOL]  TRUE for NMPRG files only               here FALSE


ISPROG_195
ISPROG
ISPROG        [BOOL]  TRUE for both PROG and NMPRG files      here FALSE


ISEXECUTABLE_196
ISEXECUTABLE
ISEXECUTABLE  [BOOL]  TRUE for PROG,NMPRG,SL,XL files         here FALSE


ISENCRYPTED_197
ISENCRYPTED
ISENCRYPTED   [BOOL]  TRUE for files encrypted by %SEC ENCRYPThere FALSE


ISQEDIT_198
ISQEDIT
ISQEDIT       [BOOL]  TRUE if the file code=111 (QEDIT)       here FALSE


ISJUMBO_199
ISJUMBO
ISJUMBO       [BOOL]  TRUE if the file is a QEDIT "Jumbo" file here FALSE


ISPRIV_200
ISPRIV
ISPRIV        [BOOL]  TRUE if the file is PRIVILEGED          here FALSE


ISDIR_201
ISDIR
ISDIR         [BOOL]  TRUE if a directory or account (POSIX)  here FALSE


ISHIDDEN_202
ISHIDDEN
ISHIDDEN      [BOOL]  TRUE if the file is "hidden" from MPE :LISTF output
                       (begins with "." or "/") (POSIX)   here FALSE


ISLINK_203
ISLINK
ISLINK        [BOOL]  TRUE if linked to another file (POSIX)  here FALSE


ISBYTESTREAM_204
ISBYTESTREAM
ISBYTESTREAM  [BOOL]  TRUE if BYTE STREAM file (POSIX)        here FALSE


ISXLSPOOLFILE_205
ISXLSPOOLFILE
ISXLSPOOLFILE [BOOL]  TRUE if NM SPOOL file                   here FALSE

%LISTF MYFILE.PUB.SYS,XL3
                 MPEX %LISTF MYFILE.PUB.SYS   PAGE 1

********************
FILE: MYFILE.PUB.SYS

FILE CODE : 0                   FOPTIONS: BINARY,FIXED,NOCCTL,STD
BLK FACTOR: 1                   CREATOR : MANAGER.VESOFT
REC SIZE: 256(BYTES)            LOCKWORD: **
                                GROUP ID: SYS
BLK SIZE: 256(BYTES)            SECURITY--READ:    ANY
EXT SIZE: 0(SECT)                         WRITE:   ANY
NUM REC: 0                                APPEND:  ANY
NUM SEC: 0                                LOCK:    ANY
NUM EXT: 0                                EXECUTE: ANY
MAX REC: 1023                           **SECURITY IS ON
                                FLAGS   : NO ACCESSORS
NUM LABELS: 0                   CREATED : SUN, AUG 11, 1991,  1:55 PM
MAX LABELS: 0                   MODIFIED: THU, DEC 24, 1992, 10:52 AM
DISC DEV #: 2                   ACCESSED: FRI, FEB 05, 1993,  8:15 AM
                                RESTORED: THU, DEC 30, 1993, 11:34 AM
                                STATE   : THU, DEC 24, 1992, 10:52 AM
SEC OFFSET: 0                   LABEL ADDR: **
UFID      : $055C0002 $4B8C11A6 $00593ABA $85033455 $1CBC9B07
VOLCLASS  : DISC


FOPTIONS_206
FOPTIONS
FOPTIONS      [INT]   FOPTIONS of a file.                     here %2001


FMTFOPTIONS_207
FMTFOPTIONS
FMTFOPTIONS   [STR]   Formatted FOPTIONS value                here BINARY,
                       FIXED,
                                                              NOCCTL, STD


CREATOR_208
CREATOR
CREATOR       [STR]   Creator name                            here MANAGER


CREATORACCOUNT_209
CREATORACCOUNT


MPE_V_and_MPE_iX_differences__CREATORACCOUNT_attribute_210
MPE/V and MPE/iX differences: CREATORACCOUNT attribute
CREATORACCOUNT
              [STR]   Creator's logon account                 here VESOFT
                      On MPE/iX systems that do not support POSIX, this applied
                       to native mode SPOOLFILES only.  On POSIX systems, all
                       MPE/iX files have this attribute.  On MPE/V machines,
                       this attribute does not exist.


OWNER_211
OWNER
OWNER         [STR]   Owner name (POSIX)                      MANAGER.VESOFT


LOCKWORD_212
LOCKWORD
LOCKWORD      [STR]   Lockword (up to 8 chars, no blanks).  Returns an empty
                       string if the file has no lockword or the user does not
                       have AM (for files within their account) or SM
                       capability.  Remember, POSIX files do not have
                       lockwords.


FILEGROUP_213
FILEGROUP
FILEGROUP     [STR]   The file's GROUPID attribute (POSIX)


CREDATE_214
CREDATE
CREDATE       [DATE]  Creation date                           here 8/11/91


CRETIME_215
CRETIME


MPE_V_and_MPE_iX_differences__CRETIME_attribute_216
MPE/V and MPE/iX differences: CRETIME attribute
CRETIME       [TIME]  Creation time (MPE/iX only)             here 1:55 PM


CREDATETIME_217
CREDATETIME


MPE_V_and_MPE_iX_differences__CREDATETIME_attribute_218
MPE/V and MPE/iX differences: CREDATETIME attribute
CREDATETIME   [STR]   Creation date and time, a 12-character string formatted
                       as "YYMMDDhhmmss", e.g.  "900522050630" means 90/05/22,
                       5:06 AM and 30 seconds.  Useful for comparing creation
                       dates and times of files.  (MPE/iX only).


ACCDATE_219
ACCDATE
ACCDATE       [DATE]  Last access date                        here 2/5/93


ACCTIME_220
ACCTIME


MPE_V_and_MPE_iX_differences__ACCTIME_attribute_221
MPE/V and MPE/iX differences: ACCTIME attribute
ACCTIME       [TIME]  Last access time (MPE/iX only)          here 8:15 AM


ACCDATETIME_222
ACCDATETIME
ACCDATETIME   [STR]   Last access date and time, "YYMMDDhhmmss" format.


MODDATE_223
MODDATE
MODDATE       [DATE]  Last modify date                        here 12/24/92


MODTIME_224
MODTIME
MODTIME       [TIME]  Last modify time                        here 10:52 AM


MODDATETIME_225
MODDATETIME
MODDATETIME   [STR]   Last modify date and time, "YYMMDDhhmmss" format.


RSTDATE_226
RSTDATE
RSTDATE       [DATE]  Last restore date                       here 12/30/93


RSTTIME_227
RSTTIME
RSTTIME       [TIME]  Last restore time                       here 11:34 AM


RSTDATETIME_228
RSTDATETIME
RSTDATETIME   [STR]   Last restore date and time, "YYMMDDhhmmss" format.


STATEDATE_229
STATEDATE
STATEDATE     [DATE]  State change date                       here 12/24/92


STATETIME_230
STATETIME
STATETIME     [TIME]  State change time (POSIX)               here 10:52 AM


STATEDATETIME_231
STATEDATETIME
STATEDATETIME [STR]   State change date and time, "YYMMDDhhmmss" format (POSIX)

%LISTF MYFILE.PUB.SYS,4
-----FILE------ EXTENTS -BLKFACT- -----SECTORS-----  DEVICE      LABEL
NAME      CODE  NUM MAX  NOW BEST USED NOW  SAVABLE  CLASS       LDEV

MYFILE           27  29   32  16      5930    1220   DISC        2
   Dev/Sector:    1/%00000242254   3/%00000242576   ...
%


BESTBLOCKFACTOR_232
BESTBLOCKFACTOR
BESTBLOCKFACTOR
              [INT]   Best blocking factor (here 16) for this file (assuming
                       file will be %ALTFILE ;SQUEEZEd).


SAVABLESECTORS_233
SAVABLESECTORS


Disc_space__selecting_by_savable_space_234
Disc space: selecting by savable space


MPE_V_and_MPE_iX_differences__SAVABLESECTORS_attribute_235
MPE/V and MPE/iX differences: SAVABLESECTORS attribute
SAVABLESECTORS
              [INT]   number of sectors savable by an %ALTFILE
                       ;SQUEEZE;BLKFACT=BEST (or, on MPE/iX, by an %ALTFILE
                       ;XLTRIM).


DEVICE_236
DEVICE
DEVICE        [STR]   Device class                            here DISC


FLABLDEV_237
FLABLDEV
FLABLDEV      [INT]   LDEV for the file label                 here 2
                      NOTE: this isn't necessarily where the file resides.


EXTENTSIZE_238
EXTENTSIZE


MPE_V_and_MPE_iX_differences__EXTENTSIZE_attribute_239
MPE/V and MPE/iX differences: EXTENTSIZE attribute
EXTENTSIZE    [INT]   # of sectors in each extent (on MPE/V systems)


LASTEXTENTSIZE_240
LASTEXTENTSIZE
LASTEXTENTSIZE [INT]  # of sectors in last extent.

%LISTF MYFILE.PUB.SYS,SEC
FILENAME     REC  TYPE  READ     APPEND   WRITE    LOCK     EXECUTE

MYFILE       80B  FA    AC       AL,GU    CR       CR       ANY


ISRELEASED_241
ISRELEASED


Released_files__finding_them_242
Released files: finding them
ISRELEASED    [BOOL]  TRUE if file is :RELEASEd               here FALSE


ISSECURED_243
ISSECURED
ISSECURED     [BOOL]  TRUE if file is :SECUREd                here TRUE


HASACD_244
HASACD
HASACD        [BOOL]  TRUE if the file has an ACD


SECURITYR_245
SECURITYR
SECURITYR     [STR]   Allowed readers                         here "AC"


SECURITYA_246
SECURITYA
SECURITYA     [STR]   Allowed appenders                       here "AL,GU"


SECURITYW_247
SECURITYW
SECURITYW     [STR]   Allowed writers                         here "CR"


SECURITYL_248
SECURITYL
SECURITYL     [STR]   Allowed lockers                         here "CR"


SECURITYX_249
SECURITYX
SECURITYX     [STR]   Allowed executers                       here "ANY"


SECURITYANY_250
SECURITYANY
SECURITYANY   [STR]   Rights of users of class ANY            here "X"


SECURITYAC_251
SECURITYAC
SECURITYAC    [STR]   Rights of users of class AC             here "R"


SECURITYAL_252
SECURITYAL
SECURITYAL    [STR]   Rights of users of class AL             here "A"


SECURITYGU_253
SECURITYGU
SECURITYGU    [STR]   Rights of users of class GU             here "A"


SECURITYGL_254
SECURITYGL
SECURITYGL    [STR]   Rights of users of class GL             here ""


SECURITYCR_255
SECURITYCR
SECURITYCR    [STR]   Rights of users of class CR             here "WL"


CSECURITYR_256
CSECURITYR


CSECURITYA_257
CSECURITYA


CSECURITYW_258
CSECURITYW


CSECURITYL_259
CSECURITYL


CSECURITYX_260
CSECURITYX


CSECURITYANY_261
CSECURITYANY


CSECURITYAC_262
CSECURITYAC


CSECURITYAL_263
CSECURITYAL


CSECURITYGU_264
CSECURITYGU


CSECURITYGL_265
CSECURITYGL


CSECURITYCR_266
CSECURITYCR
CSECURITYxxx  [STR]   Same as SECURITYxxx (where xxx can be R, A, W, ANY, AC,
                       AL, etc.) except that it factors in the group and
                       account security access matrices as well.  Not available
                       in VEFINFO.


ISBOSS_267
ISBOSS
ISBOSS        [BOOL]  TRUE if executing user is SM or AM of file's account.

              Miscellaneous:


ACDREQUIRED_268
ACDREQUIRED
ACDREQUIRED   [BOOL]  TRUE if ACDs are required (POSIX)


CHECKSUM_269
CHECKSUM
CHECKSUM      [INT]   File's checksum                         (MPE/V only)


COLDLOADID_270
COLDLOADID
COLDLOADID    [INT]   COLDLOAD ID for the file                (MPE/V only)


VALIDCOLDLOADID_271
VALIDCOLDLOADID
VALIDCOLDLOADID
              [BOOL]  TRUE if COLDLOADID is current and valid (MPE/V only)
                      (always returns TRUE on MPE/iX)


EXCLUSIVE_272
EXCLUSIVE
EXCLUSIVE     [BOOL]  TRUE if being accessed exclusively.


FULLNAME_273
FULLNAME
FULLNAME      [STR]   Fully-qualified name (up to 26 chars, no blanks), e.g.
                       "CICAT.PUB.SYS" (no lockword).


FULLNAMELOCK_274
FULLNAMELOCK
FULLNAMELOCK  [STR]   Fully-qualified name (up to 35 chars, no blanks), e.g.
                       "GOD/BOG.PUB.VESOFT" (with lockword).


LABELEOF_275
LABELEOF
LABELEOF      [INT]   Number of currently written user labels.


LABELFLIMIT_276
LABELFLIMIT
LABELFLIMIT   [INT]   Maximum number of user labels.


LOADED_277
LOADED
LOADED        [BOOL]  TRUE if loaded (:RUN or :ALLOCATEd).


ID_278
ID
ID            [STR]   Returns the text associated with this file.


IDCONTAINS_279
IDCONTAINS
IDCONTAINS(..)[BOOL]  TRUE if the string passed to this function appears in the
                       file's identification string.


NUMLINKS_280
NUMLINKS
NUMLINKS      [INT]   Number of files LINKED to this file (POSIX)


OPENEDSYSFAIL_281
OPENEDSYSFAIL


MPE_V_and_MPE_iX_differences__OPENEDSYSFAIL_attribute_282
MPE/V and MPE/iX differences: OPENEDSYSFAIL attribute
OPENEDSYSFAIL [BOOL]  TRUE if a system failure occurred while the file was
                       FOPENed and the file has not been FOPENed since then
                       (useful for KSAM files to determine if KSAMUTIL
                       >KEYINFO;RECOVER should be run against them).
                       (Not available under MPE/iX).


PATH_283
PATH
PATH          [STR]   The PATH portion of a filename.         (POSIX)
                      For the file "/ROOTDIR/subdir/filename", the PATH is
                       "/ROOTDIR/subdir/".


RESTORED_284
RESTORED


MPE_V_and_MPE_iX_differences__RESTORED_attribute_285
MPE/V and MPE/iX differences: RESTORED attribute
RESTORED      [BOOL]  TRUE if being :RESTOREd.
                       (not available under MPE/iX).


STORED_286
STORED


MPE_V_and_MPE_iX_differences__STORED_attribute_287
MPE/V and MPE/iX differences: STORED attribute
STORED        [BOOL]  TRUE if being :STOREd.
                       (not available under MPE/iX).


READING_288
READING
READING       [BOOL]  TRUE if opened for read access.


WRITING_289
WRITING
WRITING       [BOOL]  TRUE if opened for write access.

              Functions:


ACCESSIBLE_290
ACCESSIBLE
ACCESSIBLE(S) [BOOL]  TRUE if you -- the running user -- have the access
                       specified by string S to the file, e.g.
                       ACCESSIBLE("RWX") is TRUE if you have Read, Write, and
                       eXecute access to the file.


ACCESSIBLEBY_291
ACCESSIBLEBY
ACCESSIBLEBY(S1,S2)
              [BOOL]  TRUE if the file has ACDs and the user indicated by S2
                       has the access specified by S1 to the file.  For
                       instance, ACCESSIBLEBY("RW","JACK.PROD") is TRUE if
                       JACK.PROD has Read and Write access to the file.  S2 may
                       also be "@.account" or "@.@" --
                       ACCESSIBLEBY("X","@.DEV") is TRUE if the entire DEV
                       account has eXecute access to the file;
                       ACCESSIBLEBY("R","@.@") is TRUE if everybody has been
                       granted access to the file.

                       NOTE:At the moment, this only returns TRUE for files
                             with ACDs; also, it only looks at what access the
                             user has been explicitly allowed -- it does not
                             consider that the user may be allowed full access
                             because he is the file's creator, AM, or SM.  This
                             may be changed in future versions.


DEVICESECTORS_292
DEVICESECTORS
DEVICESECTORS(I)
              [INT]   The number of sectors of the current file located on LDEV
                       I, e.g.  DEVICESECTORS(2).


MATCHES_293
MATCHES
MATCHES(S)    [BOOL]  TRUE if filename matches fileset S, e.g.
                       MATCHES("AP@.SOURCE.@").


NEWERTHAN_294
NEWERTHAN
NEWERTHAN(S)  [BOOL]  TRUE if the file has been modified later than the
                       corresponding file in the targetfileset specified by the
                       string (see "Target Filesets", above).  Because MPE may
                       change the modify date for program files when you merely
                       RUN them, MPEX uses the create date rather than the
                       modify date if the targetfile is a program file (PROG or
                       NMPRG).  If the targetfile doesn't exist, NEWERTHAN(..)
                       returns TRUE.


ONDEVICE_295
ONDEVICE
ONDEVICE(I)   [BOOL]  TRUE if at least one extent of the current file is
                       located on LDEV I, e.g.  ONDEVICE(1).

              Text processing and string searching:


FSEARCHSTRING_296
FSEARCHSTRING
FSEARCHSTRING(S)
              [INT]   Returns the number of lines containing the string S in
                       the text of the current file.  E.g.

   %LISTF @.SOURCE(FSEARCHSTRING('FOO')>0)

                       finds all the files in the SOURCE group which have one
                       or more lines containing the string 'FOO'.


FCONTAINS_297
FCONTAINS
FCONTAINS(S)  [BOOL]  Returns TRUE if the string is in the file.  For example:

   %LISTF @.SOURCE(FCONTAINS('FOO'))

                       finds all the files in the SOURCE group which have one
                       or more lines containing the string 'FOO'.  This is
                       equivalent to the example for FSEARCHSTRING, but you
                       don't include ">0" as part of the selection criteria.


FSEARCHEXP_298
FSEARCHEXP
FSEARCHEXP(S) [INT]   Returns the number of lines that match the logical
                       expression -- just like the ones that can be passed to
                       %PRINT ;SEARCH= -- specified by S.  Remember, however,
                       that since in this context S is a STRING, it must be
                       enclosed in quotes:

   %LISTF @.SOURCE (FSEARCHEXP("'CUST-NO' or 'CUST-NAME'")>0)

                       will find all files that have at least one line
                       containing EITHER the string 'CUST-NO' or the string
                       'CUST-NAME'.

                       In fact, S can include (in addition to the logical
                       expression used by ;SEARCH=) any of the MPEX %PRINT
                       parameters (although not all of them are useful in this
                       context).

                       For example, you might say

   %LISTF @.FAIRY.TALES (FSEARCHEXP("'happily';START=50;END=60")>0)

                       which means "list all of the files in the FAIRY.TALES
                       group that have the word 'happily' between lines 50 and
                       60.

                       Perhaps the most useful keyword in this context is
                       ;MAX=, which means stop reading the file after finding a
                       given number of occurrences of the string.

  %LISTF @.TALL.TALES(FSEARCHEXP("CL'blue ox';MAX=2")=2), 3

                       shows you the create/restore/modify/access dates (",3")
                       of all the files in the TALL.TALES group that contain at
                       least two occurrences of the string "blue ox" (upper- or
                       lowercase), and stops searching each file after finding
                       two occurrences of the string.

FILE ATTRIBUTES PERTAINING TO IMAGE DATASETS


File_attributes_pertaining_to_IMAGE_datasets__299
File attributes pertaining to IMAGE datasets


Selection_criteria__for_databases_300
Selection criteria: for databases
NOTE: These file attributes are relevant only for IMAGE datasets -- if the
current file is not an IMAGE dataset, these attributes will be set to dummy
values ("" for strings, -1 for numbers).

%LISTF CUST01.VESOFT.LIST,DB

FILENAME SET NAME   TYPE LDEV  ENTRY   CAPA-  %FULL BLK SECTORS %BLOCK SECTRS
                               COUNT    CITY        FCT         WASTED WASTED

CUST01   CUST          M   2   13856   19009  72.9%  19   17024   0.4%     62


DBSETNAME_301
DBSETNAME
DBSETNAME     [STR]   Dataset name                            here "CUST"


DBSETTYPE_302
DBSETTYPE
DBSETTYPE     [STR]   Dataset type (M, D, or A)               here "M"


DBSETENTRIES_303
DBSETENTRIES
DBSETENTRIES  [INT]   # of dataset entries                    here 13856


DBSETCAPACITY_304
DBSETCAPACITY
DBSETCAPACITY [INT]   Dataset capacity                        here 19009


DBSETFULLNESS_305
DBSETFULLNESS
DBSETFULLNESS [REAL]  Entries//capacity                       here 0.729


DBSETHIGHWATERMARK_306
DBSETHIGHWATERMARK
DBSETHIGHWATERMARK
              [INT]   Highwatermark (highest record number ever used; useful
                       only in a detail dataset).
                       Note:you can calculate the deleted chain length as
                             DBSETHIGHWATERMARK - DBSETNUMENTRIES.


DBSETBLOCKFACTOR_307
DBSETBLOCKFACTOR
DBSETBLOCKFACTOR
              [INT]   Dataset blocking factor                 here 19


DBSETENTRYLENGTH_308
DBSETENTRYLENGTH
DBSETENTRYLENGTH
              [INT]   Dataset data entry length (in words).


DBSETNUMPATHS_309
DBSETNUMPATHS
DBSETNUMPATHS [INT]   Number of paths linked to this dataset.


DBSETMEDIALENGTH_310
DBSETMEDIALENGTH
DBSETMEDIALENGTH
              [INT]   Dataset "media record" length, i.e.  length of each
                       record including IMAGE pointers.


DBSETBLOCKSIZE_311
DBSETBLOCKSIZE
DBSETBLOCKSIZE
              [INT]   Actual size (in words) of each dataset block on disc.


DBSETBLOCKWASTAGE_312
DBSETBLOCKWASTAGE
DBSETBLOCKWASTAGE
              [REAL]  Fraction (from 0 to 1) of each dataset block that is
                       wasted (because DBSETBLOCKSIZE is not a multiple of 128
                       words).

FILE ATTRIBUTES PERTAINING TO PROGRAMS


File_attributes_pertaining_to_programs__313
File attributes pertaining to programs


Selection_criteria__for_program_files_314
Selection criteria: for program files
NOTE: These file attributes are relevant only for program files -- if the
current file is not a program file, these attributes will be set to dummy
values (usually 0 for integers, FALSE for booleans, and "" for strings).

All of these file attributes must be referred to as "PROG.attrvar".  The
"PROG." simply tells MPEX that this attribute pertains specifically to program
files (just like "RFILE." tells MPEX -- in those contexts, like %REPEAT ...
%FORFILES, where MPEX doesn't automatically assume it -- that the attribute
pertains to files in general).

Although "RFILE." can usually be omitted for general file attributes (except in
%REPEAT ...  %FORFILES), "PROG." can not be omitted but must always be
specified if you want to get program file information.

%LISTF DBUTIL.PUB.SYS,5
FILENAME  MAXDATA STACK DLSIZE DBSIZE #SEGS  CAPABILITIES

DBUTIL      31000  1200      0   3296     4  BA IA PM


FMTCAPS_315
FMTCAPS
PROG.FMTCAPS  [STR]   Formatted capabilities                  here "BA IA PM"


PMCAP_316
PMCAP


Privileged_mode__finding_PM_programs_317
Privileged mode: finding PM programs
PROG.PMCAP    [BOOL]  TRUE if program has PM capability       here TRUE


MRCAP_318
MRCAP
PROG.MRCAP    [BOOL]  TRUE if program has MR capability       here FALSE


DSCAP_319
DSCAP
PROG.DSCAP    [BOOL]  TRUE if program has DS capability       here FALSE


PHCAP_320
PHCAP
PROG.PHCAP    [BOOL]  TRUE if program has PH capability       here FALSE


IACAP_321
IACAP
PROG.IACAP    [BOOL]  TRUE if program has IA capability       here TRUE


BACAP_322
BACAP
PROG.BACAP    [BOOL]  TRUE if program has BA capability       here TRUE


HASPRIVSEG_323
HASPRIVSEG


Privileged_mode__finding_programs_with_PM_segments_324
Privileged mode: finding programs with PM segments
PROG.HASPRIVSEG
              [BOOL]  TRUE if program has at least one permanently privileged
                       segment.


ZERODB_325
ZERODB
PROG.ZERODB   [BOOL]  TRUE if program was :PREPed with ;ZERODB.


NUMSEGS_326
NUMSEGS
PROG.NUMSEGS  [INT]   # of code segments in program           here 4


DBSIZE_327
DBSIZE
PROG.DBSIZE   [INT]   # of words in program global variable (DB) area,here 3296


STACK_328
STACK
PROG.STACK    [INT]   Program's :PREP-time ;STACK= parm       here 1200


DL_329
DL
PROG.DL       [INT]   Program's :PREP-time ;DL= parm          here 0


MAXDATA_330
MAXDATA
PROG.MAXDATA  [INT]   Program's :PREP-time ;MAXDATA= parm     here 31000


ISOCTCOMPED_331
ISOCTCOMPED


MPE_V_and_MPE_iX_differences__PROG_ISOCTCOMPED_attribute_332
MPE/V and MPE/iX differences: PROG.ISOCTCOMPED attribute
PROG.ISOCTCOMPED
              [BOOL]  TRUE if program was :OCTCOMPed (MPE/iX only).

FILE ATTRIBUTES PERTAINING TO SPOOL FILES


File_attributes_pertaining_to_SPOOL_files__333
File attributes pertaining to SPOOL files


Selection_criteria__for_SPOOL_files_334
Selection criteria: for SPOOL files
NOTE: These file attributes are relevant only for spool files, and should thus
be used only on those commands that handle spool files (like %ALTSPOOLFILE,
%DELETESPOOLFILE, or %SHOWOUT).  If you use them in connection with normal
files, you'll get unpredictable information.

All of these file attributes must be referred to as "SPOOL.attrvar".  The
"SPOOL." simply tells MPEX that this attribute pertains specifically to spool
files (just like "RFILE." tells MPEX -- in those contexts, like %REPEAT ...
%FORFILES, where MPEX doesn't automatically assume it -- that the attribute
pertains to files in general).


SPOOL_attrvar_335
SPOOL.attrvar
Although "RFILE." can usually be omitted for general file attributes (except in
%REPEAT ...  %FORFILES), "SPOOL." can not be omitted but must always be
specified if you want to get spool file information.

:RUN SPOOK5.PUB.SYS
> SHOW 970
FILE   #JOB    FNAME    STATE  DEV/CL   PR COP RFN OWNER
O970   #J350   $STDLIST READY  LP        3   1     MANAGER.VESOFT
FILE   LDEV    LABEL      SECTORS       LINES      TIME
O970   %2    %1173436       40           87        12:15  2/ 9/91


ISACTIVE_336
ISACTIVE
SPOOL.ISACTIVE [BOOL] Spool file STATE is ACTIVE              here FALSE


ISREADY_337
ISREADY
SPOOL.ISREADY  [BOOL] Spool file STATE is READY               here TRUE


ISOPENED_338
ISOPENED
SPOOL.ISOPENED [BOOL] Spool file STATE is OPENED              here FALSE


ISLOCKED_339
ISLOCKED
SPOOL.ISLOCKED [BOOL] Spool file STATE is LOCKED              here FALSE


ISDEFERRED_340
ISDEFERRED
SPOOL.ISDEFERRED                                              here FALSE
               [BOOL] Spool file STATE is DEFERRED            (MPE/iX only)


ISSPSAVE_341
ISSPSAVE


MPE_V_and_MPE_iX_differences__SPOOL_ISSPSAVE_attribute_342
MPE/V and MPE/iX differences: SPOOL.ISSPSAVE attribute
SPOOL.ISSPSAVE [BOOL] Spool file has SPSAVE set (MPE/iX only)


OUTPRI_343
OUTPRI
SPOOL.OUTPRI   [INT]  Output priority                         here 3


JOBTYPE_344
JOBTYPE
SPOOL.JOBTYPE  [INT]  1 if created by session                 here 2 (job)
                      2 if created by job,
                      3 if created by job and >INPUT from tape,
                      0 if created by session and >INPUT from tape


JOBNUMBER_345
JOBNUMBER
SPOOL.JOBNUMBER [INT] Creating job number                     here 350


USER_346
USER
SPOOL.USER     [STR]  Creating user name                      here "MANAGER"


ACCOUNT_347
ACCOUNT
SPOOL.ACCOUNT  [STR]  Creating account name                   here "VESOFT"


JSNAME_348
JSNAME
SPOOL.JSNAME   [STR]  Creating job/session name.


FILE_349
FILE
SPOOL.FILE     [STR]  Spool filename                          here "$STDLIST"


SPOOLFILENUM_350
SPOOLFILENUM
SPOOL.SPOOLFILENUM
               [INT]  Spool file number (#Oxxx)               here 970


HASFORMSMSG_351
HASFORMSMSG
SPOOL.HASFORMSMSG
               [BOOL] TRUE if has forms message.


DEVICE_352
DEVICE
SPOOL.DEVICE   [STR]  Output device class                     here "LP"
                         NOTE: numeric devices (LDEV 6 for instance) need to be
                       quoted, as in "6".


JOBABORTED_353
JOBABORTED
SPOOL.JOBABORTED
              [BOOL]  TRUE if job aborted as a result of an error in a command
                       that was not preceded by "!CONTINUE".


NUMCOPIES_354
NUMCOPIES
SPOOL.NUMCOPIES [INT] Number of copies                        here 1


NUMLINES_355
NUMLINES
SPOOL.NUMLINES [INT]  Number of lines                         here 87


READYDATE_356
READYDATE
SPOOL.READYDATE
               [DATE] Date the file was made ready            here 2/9/91


READYTIME_357
READYTIME
SPOOL.READYTIME
               [TIME] Time the file was made ready            here 12:15

GROUP AND ACCOUNT ATTRIBUTES OF FILES


GROUP_and_ACCOUNT_attributes_of_files_358
GROUP and ACCOUNT attributes of files


Selection_criteria__for_files__359
Selection criteria: for files


DIRGROUP_360
DIRGROUP


DIRACCOUNT_361
DIRACCOUNT
Suppose you want to find all program files that were :PREPed with ";CAP=PH",
but that reside in groups (or accounts) that don't have PH capability.  You can
easily select PROG.PHCAP, but how do you select based on attributes of the
group and/or account the file is in? Very easily!  You just use
"DIRGROUP.attrvar" and "DIRACCOUNT.attrvar" in the selection condition (or
"RFILE.DIRGROUP.attrvar"/"RFILE.DIRACCOUNT.attrvar" in a %REPEAT ...
%FORFILES)!

In the above example, you would simply say

   %LISTF @.@.@(PROG.PHCAP and NOT DIRGROUP.CAP("PH"))
      or
   %LISTF @.@.@(PROG.PHCAP and NOT DIRACCOUNT.CAP("PH"))

For a complete list of group and account attributes, see the MPE Group
Attribute Variables and MPE Account Attribute Variables in the Object Attribute
Variables section of the VEAUDIT User Manual.

Actually, DIRGROUP and DIRACCOUNT are really just shorthand for VEGROUPINFO and
VEACCTINFO; e.g.

   DIRGROUP.CAP("PH")
      is the same as
   VEGROUPINFO(RFILE.GROUP+"."+RFILE.ACCOUNT).CAP("PH")

See Appendix for more information on these and other functions.

JOB/SESSION ATTRIBUTES


Job_Session_attributes__362
Job/Session attributes


Selection_criteria__for_jobs_sessions_363
Selection criteria: for jobs/sessions
NOTE: unlike the previous attributes, which all pertain to some type of files
("flat" files, databases, spoolfiles, etc.), or to MPE groups and accounts,
these are attributes of jobs and/or sessions.  They can only be used in
commands and/or expressions that handle MPE jobs/sessions


RJOB__364
RJOB.


VEJOBINFO_365
VEJOBINFO
(like ![RJOB.attrvar] in a %REPEAT...FORJOBS construct, and the
VEJOBINFO(...).attrvar function).

When we use "job" in the description of the following attribute variables, we
really mean "job or session".  However, some attribute variables are meaningful
only for jobs (e.g.  ISSTDLISTDELETE, OUTPRI, NUMCOPIES, etc.), while others
make sense only for sessions (HPDTCPORTID, ISQUIET, etc.).  If you try to use a
JOB attribute against a SESSION, you may get an error.

Note that all the attribute variables of type string [STR] have no trailing
blanks.


FMTLOGON_366
FMTLOGON
FMTLOGON      [STR]   Job logon, formatted as "jobname,user.account,group".


FMTJOB_367
FMTJOB
FMTJOB        [STR]   Job number, formatted as "#Snnn" or "#Jnnn".


JSNAME_368
JSNAME
JSNAME        [STR]   Job/session name.


USER_369
USER
USER          [STR]   User name.


GROUP_370
GROUP
GROUP         [STR]   Group name.


ACCOUNT_371
ACCOUNT
ACCOUNT       [STR]   Account name.


HOMEGROUP_372
HOMEGROUP
HOMEGROUP     [STR]   Home group name.


INTROTIME_373
INTROTIME
INTROTIME     [TIME]  Time the job was introduced.


INTRODATE_374
INTRODATE
INTRODATE     [DATE]  Date the job was introduced.


LDEVIN_375
LDEVIN
LDEVIN        [STR]   Job input device.


LDEVLIST_376
LDEVLIST
LDEVLIST      [STR]   Job output device.


CURRENTCMD_377
CURRENTCMD
CURRENTCMD    [STR]   Last MPE command the job executed.


INPRI_378
INPRI
INPRI         [INT]   Job input priority (15 = HIPRI).


OUTPRI_379
OUTPRI
OUTPRI        [INT]   Job $STDLIST output priority.


NUMCOPIES_380
NUMCOPIES
NUMCOPIES     [INT]   Job $STDLIST number of copies.


ISDEFERRED_381
ISDEFERRED
ISDEFERRED    [BOOL]  TRUE if the job is deferred (i.e.  INPRI < JOBFENCE).


MAINPIN_382
MAINPIN
MAINPIN       [INT]   Job's main PIN.


ISRESTARTABLE_383
ISRESTARTABLE
ISRESTARTABLE [BOOL]  TRUE if the job is restartable.


CPULIMIT_384
CPULIMIT
CPULIMIT      [INT]   Job's CPU time limit.


ISEXEC_385
ISEXEC
ISEXEC        [BOOL]  TRUE if job is executing.


ISSUSP_386
ISSUSP
ISSUSP        [BOOL]  TRUE if job is suspended.


ISWAIT_387
ISWAIT
ISWAIT        [BOOL]  TRUE if job is waiting.


ISINIT_388
ISINIT
ISINIT        [BOOL]  TRUE if job is being initialized.


ISSCHED_389
ISSCHED
ISSCHED       [BOOL]  TRUE if job is scheduled.


ISQUIET_390
ISQUIET
ISQUIET       [BOOL]  TRUE if user has issued a SET MSG=OFF command


STATE_391
STATE
STATE         [STR]   Job state ("EXEC", "SUSP", etc.).


LOCATTR_392
LOCATTR
LOCATTR       [INT]   Local attribute of user ID that job is logged on to.


HPDTCPORTID_393
HPDTCPORTID
HPDTCPORTID   [STR]   The DTC PORT address/ID for the session.


INSPOOLFILENUM_394
INSPOOLFILENUM
INSPOOLFILENUM
              [INT]   Job input spool file number.


OUTSPOOLFILENUM_395
OUTSPOOLFILENUM
OUTSPOOLFILENUM
              [INT]   Job output spool file number.


ISSTDLISTDELETE_396
ISSTDLISTDELETE
ISSTDLISTDELETE
              [BOOL]  TRUE if job did a :SET STDLIST=DELETE.


PRIVATE_397
PRIVATE
PRIVATE       [BOOL]  TRUE if the job's $STDLIST spoolfile is PRIVATE


SPSAVE_398
SPSAVE
SPSAVE        [BOOL]  TRUE if the job's $STDLIST spoolfile should be saved

SECURITY/3000 USER PROFILE ATTRIBUTES


SECURITY_user_profile_attributes__399
SECURITY user profile attributes


Selection_criteria__SECURITY_user_profile_attribute_400
Selection criteria: SECURITY user profile attribute

In addition to all of the various MPE-related attributes described above, MPEX
also gives SECURITY users access to various "user profile" attributes, like the
user's real name, last logon date/time, or even user-defined fields.

You can access these attributes using the VEPROFILEINFO(profile).attr and
VEPROFILEEXISTS(profile) functions (see Appendix for details).

For a complete listing of user profile attributes, see "User Profile Attribute
Variables and Functions" in the Listing User Profiles section of the
SECURITY User Manual.


USING_MPEX_TO_COMPILE_PROGRAMS_401
USING MPEX TO COMPILE PROGRAMS


MPE_V_compilers_402
MPE/V compilers


_COBOL_403
%COBOL


_COBOLII_404
%COBOLII


_COBOLIIX_405
%COBOLIIX


_FORTRAN_406
%FORTRAN


_FTN_407
%FTN


_RPG_408
%RPG


_PASCAL_409
%PASCAL


_SPL_410
%SPL


MPE_iX_compilers_411
MPE/iX compilers


_CCXL_412
%CCXL


_COB74XL_413
%COB74XL


_COB85XL_414
%COB85XL


_FTNXL_415
%FTNXL


_PASXL_416
%PASXL


_RPGXL_417
%RPGXL


MPE_iX_compilers__418
MPE/iX compilers


_CCXLLK_419
%CCXLLK


_COB74XLK_420
%COB74XLK


_COB85XLK_421
%COB85XLK


_FTNXLLK_422
%FTNXLLK


_PASXLLK_423
%PASXLLK


_RPGXLLK_424
%RPGXLLK

Say that you change your COPYLIB -- now you have to recompile all of your many
COBOL programs.  (Even if you think that the COPYLIB module you changed affects
only 10 programs, you may easily be mistaken, and if you are, a partial
recompile may do more harm than good!) MPEX lets you do this in one command.

Note: Although the examples that follow show the COBOL compiler, MPEX has
      commands to compile using C, FORTRAN, Pascal, RPG, and SPL as well.  The
      format for each of these commands is virtually identical, so once you've
      learned how to use one compiler, learning the others is a fairly simple
      task.  At the end of this section, specific differences between our
      commands and their MPE equivalents will be discussed.

What does the

   %COBOL AP@.SOURCE,AP@.PUB,,,,,MAXDATA=30000;CAP=PH

command do? Well, it takes all the files in the fileset "AP@.SOURCE" and
compiles (and :PREPs) them into program files with the same names except that
they reside in the PUB group (that's what the AP@.PUB indicates).  Since the
"prepparms" parameter was specified (MAXDATA=30000;CAP=PH), all the :PREPs will
take place with those parameters.

This is one command that you might want to do in batch mode rather than online
(otherwise it might tie up your terminal for quite a while).  Saying

   %$COBOL AP@.SOURCE,AP@.PUB,,,,,MAXDATA=30000;CAP=PH

will execute all the compiles in a batch job stream (that's what the "$" before
the "COBOL" indicates).  If there are any compile errors, the job stream will
send you a message indicating this; in any case, the job stream will also send
you a message when it's done.  (Remember that the "$" prefix can be used in
front of any command to execute it in batch.)

Note that although the command is called %COBOL, it's actually more like a
:COBOLPREP -- the second parameter is the program file (not the USL file).  If
you want to specify the USL fileset, too, you can -- it's the sixth parameter
(after the "newfileset" and before the "prepparms").  If you only want to do
compiles, not :PREPs, see below.

GENERAL SYNTAX:

General syntax for CM compilers:

%CMcompiler  textfileset
                  [,[progfileset]
                  [,[listfileset]
                  [,[masterfileset]
                  [,[newfileset]
                  [,[uslfileset]
                  [,[prepparms]]]]]]]

Compilers available: COBOL, COBOLII, COBOLIIX, FORTRAN, FTN, PASCAL, RPG, SPL

General syntax for NM compilers (compile only, no link):

%NMcompiler textfileset
                 [,[objectfileset]
                 [,[listfileset]
                 [,[mastfileset]                           (COBXL only)
                 [,[newfileset]                            (COBXL only)
                 [,[libfileset]                            (PASXL only)
                 [;INFO= infostring
                 [;WKSP= workspacename                     (COBXL only)
                 [;XDB= xdbfilename ]]]]]]]]               (COBXL only)

Compilers available: CCXL, COB74XL, COB85XL, FTNXL, PASXL, RPGXL

General syntax for NM compilers (with linking):

%NMcompilerLK textfileset
                  [,[progfileset]
                  [,[listfileset]
                  [,[mastfileset]                          (COBXL only)
                  [,[newfileset]                           (COBXL only)
                  [,[libfileset]                           (PASXL only)
                  [;INFO= infostring
                  [;WKSP= workspacename                    (COBXL only)
                  [;XDB= xdbfilename]]]]]]]]               (COBXL only)

Compilers available: CCXLLK, COB74XLK, COB85XLK, FTNXLLK, PASXLLK, RPGXLLK

In the above syntax diagrams, each of the filesets described MUST be entered in
the order given, or a "," should be included as a placeholder.  This is true
even for the ;INFO=, ;WKSP=, and ;XDB= parameters.  If you do not specify all
the files or filesets before any of these parameters, you must include
placeholders as shown in these examples:

     %RPG GL###S,GL000P,,,,GL000U,MAXDATA=30000;CAP=PH;RL=XRL3
     %COB85XL MYSRC,,,,;WKSP="MYWORK"

Also note that for the NM compilers, COBOL has two additional filesets as well
as additional keywords while the PASCAL compiler has only one additional
fileset.

COMPILING MANY SOURCES INTO ONE PROGRAM

The "%COBOL AP@.SOURCE,AP@.PUB" command we talked about above compiled each
source file in AP@.SOURCE into a corresponding program file in AP@.PUB.

What if you organize your system by having a single main body source file (e.g.
the main menu) and a lot of $CONTROL DYNAMIC subroutines? MPEX can handle this,
too:

   %COBOL GL###S,GL000P,,,,GL000U,MAXDATA=30000;CAP=PH;RL=XRL3

This will compile all the sources in the fileset GL###S into the program file
GL000P.  Incidentally, it specifies that all the sources are to be compiled
into the USL file GL000U; you don't have to specify the USL file on this kind
of compile, but you'd often want to (in case you want to later recompile just
one of the modules).

COMPILING WITHOUT :PREPing

If you want to compile but not :PREP, you may just specify the USL fileset (or
a single USL file) without a program fileset.  For instance, saying

   %COBOL AP@.SOURCE,,,,,AP@U.PUB

will compile all the files in AP@.SOURCE into correspondingly-named USL files
in the fileset AP@U.PUB (each USL file will have the same name as the source
file but with a U at the end).  Similarly,

   %COBOL GL###S,,,,,GL000U

will compile all the GL###S files into the single USL file GL000U.

COMPILING WITH A COPYLIB

To compile with a COPYLIB, you should simply issue an ordinary

   :FILE COPYLIB=copylibfilename

file equation.  If you're compiling in batch, e.g.

   %$COBOL GL###S,,,,,GL000U

that's OK -- just issue the :FILE COPYLIB= file equation online and MPEX will
automatically copy it into the job stream.

SPECIFIC DIFFERENCES BETWEEN MPE AND MPEX COMPILERS


SPECIFIC_DIFFERENCES_BETWEEN_MPE_AND_MPEX_COMPILE_COMMANDS_425
SPECIFIC DIFFERENCES BETWEEN MPE AND MPEX COMPILE COMMANDS

In general, MPEX follows the same syntax as MPE (or MPE/iX) to compile
programs.  As the COBOL examples above show, however, certain portions of the
command may be a FILESET instead of a single file name.  Here are some other
notable differences between our commands and MPE:

  *  The MPE/V compilers FTN and PASCAL do not support the "master file" and
     "new file" parameters supported by some of the other compilers (COBOL,
     FORTRAN, RPG, and SPL); however, they are included in these commands for
     consistency's sake -- you should always skip them.

  *  When compiling using the MPE/iX compilers, you could specify the ";INFO="
     string immediately after the last actual parameter given.  i.e.  if you
     compile a C program using an ";INFO=" string without specifying the object
     and list files, you could simply say:

       :CCXL MYSOURCE;INFO="compiler-directives"

     However, MPEX requires you to insert placeholders in the command for any
     parameter not specified, so to do the above command in MPEX, you would
     need to type:

       %CCXL MYSOURCE , , ;INFO="compiler-directives"

USING THIRD PARTY COMPILERS WITH MPEX


Using_third_party_compilers_with_MPEX_426
Using third party compilers with MPEX

The above commands and examples all deal with using compilers supplied by HP
for many of their third generation languages (COBOL, FORTRAN, PASCAL, RPG), but
what about fourth generation languages (such as TRANSACT) or compilers supplied
by a "third party"? While we don't have specific commands for all of the
compilers available, it is a simple matter to create a command file that uses
%REPEAT ...  %FORFILES to compile several files with one command.

Here is an example command file that accepts two parameters -- a source fileset
and a target mask.  All of the files in the source fileset are compiled using
the generic compiler into the files specified by the target "mask".

     PARM CS$SOURCESET
     ANYPARM TARGETMASK
     REPEAT
        FILE SOURCE=!MPEXCURRENTFILE
        FILE TARGET=![OBJECTFILE(!TARGETMASK)]
        ECHO -----Compiling !mpexcurrentfile
        RUN ANY.GENERIC.COMPILER;INFO="*SOURCE,$NEWPASS";PARM=12345

   (if this is on a CLASSIC system or a CM compiler)
        PREP $OLDPASS,*TARGET
   (if this is a native mode compiler)
        LINKEDIT $OLDPASS;TO=*TARGET

     FORFILES !SOURCESET

As you can see, this is a very simple example and does not take into account
such possibilities as compiling multiple files into a single program file or
redirecting the output listings to a printer.  This example presumes that the
name(s) of the files to be used are passed as an ;INFO= parameter, but could
just as easily be specific file-equations for the source and object files.

If the compiler you are using prompts for the names of the files to use as the
source, object, and even the resulting program, you can use this example:

     PARM CS$SOURCESET
     ANYPARM TARGETMASK
     REPEAT
        ECHO -----Compiling !mpexcurrentfile
        RUN ANY.GENERIC.COMPILER&
            ;INPUT="!MPEXCURRENTFILE";INPUT="$NEWPASS"
        (PREP or LINK as appropriate)
     FORFILES !SOURCESET

As you may have noticed, MPEXCURRENTFILE corresponds to the actual (fully
qualified) filename of the sourcefile for each repetition through the loop, and
the OBJECTFILE(..) function takes a parameter which it applies to the
CURRENTFILE to create a TARGET file name.


MPEX_HOOK__427
MPEX HOOK

Let's say you're working in EDITOR.  You write your program, compile it, find
that there's a 'bug', make some changes, run it, make some more changes -- the
usual program development process.  Unfortunately, with EDITOR, this will
involve a lot of effort.  You have to:

   * Make some changes to your program
   * Keep your program
   * Exit EDITOR
   * Compile your program
   * Enter EDITOR
   * Text your program
   * Make some more changes
   * Keep it again
   * Exit EDITOR
   * Run your program
   * Enter EDITOR
   * Text your program again
   * Make some more changes...

Much of your time is spent in doing nothing more than texting and keeping your
program, exiting and entering EDITOR.  This is true not only of EDITOR, but
also of QUERY, BASIC, and many other programs.  It would make sense to have any
program be able to execute any MPE command -- including compiles, RUNs, and
UDCs.

We let you execute these commands, and many more, from any of these programs.
For instance, you can say:

   :RUN EDITOR.PUB.VESOFT;LIB=P
   /TEXT MYSRC
   << modify your source >>
   /KEEP MYSRC
   /%:COBOL MYSRC,MYUSL
   << fix the 'bugs' the compile discovered >>
   /KEEP MYSRC
   /%:COBOL MYSRC,MYUSL
   /%:PREP MYUSL,MYPROG
   /%:RUN MYPROG
   << make more modifications >>
   /%Q                            << assuming Q is your QUERY UDC >>
   << run QUERY to examine your data base >>
   >EXIT
   << exit from QUERY back into EDITOR! >>
   /EXIT
   :    << you're back in MPE >>

As you see, you've not only saved a lot of time for yourself but you've also
saved a lot of computer resources by executing MPE commands directly from
EDITOR!

The commands could just as easily have been MPEX commands -- for instance, if
your program aborts, you can, without exiting EDITOR, say:

   /%ALTFILE MYDATA; FLIMIT=FLIMIT+1000

All you need to do to use the new (HOOKed) version of EDITOR is to

   :RUN EDITOR.PUB.VESOFT;LIB=P

Actually, MPEX HOOKed programs have a number of valuable features in addition
to just being able to execute MPEX commands from them:

   * A REDO facility is available that lets you redo up to the last 1000
     commands that you've typed in the program (just like MPEX %REDO).  This
     doesn't just mean "redo the MPEX commands you typed" -- this includes all
     the commands you've entered in this particular execution of this program.

     For instance, say that you make an error in an 8-line QUERY >REPORT -- you
     can redo the entire statement, make one modification, and have QUERY
     immediately re-execute all 8 commands.

   * You can activate the MPEX HOOKed program's father process without
     terminating the MPEX HOOKed program itself.  For instance, if from within
     MPEX (or any other process-handling environment) you type:

        %QUERY.PUB.VESOFT;LIB=P;LIB=P

     and then when in QUERY type

        >%%

     QUERY will be suspended and the father process (in this case, MPEX) will
     be re-activated.  You could then execute whatever MPEX commands you like
     (including other %RUNs), and then, whenever you want to, type:

        %QUERY.PUB.VESOFT;LIB=P;LIB=P

     QUERY will be re-activated (which will be quite a bit faster than
     re-%RUNing it from scratch); your database will still be open, records
     that you did a >FIND on will still be found, etc.

   * If you have SM capability, the program will be allowed to SAVE FILES IN
     OTHER ACCOUNTS.  Thus, SM users of the MPEX HOOKed EDITOR can now /KEEP
     across account boundaries; SM users of the MPEX HOOKed FCOPY can specify
     ;TO=;NEW files in other accounts; and so on.

   * Finally, you can (as we discussed earlier) execute arbitrary MPEX commands
     and MPE commands (including compile, %PREP, %RUN, and UDCs) from within
     any MPEX HOOKed program, e.g.  EDITOR, QUERY, etc.

REDOing SUBSYSTEM COMMANDS

Just like MPEX lets you save, %REDO, %LISTREDO, and %DO up to the last 1000 (or
even more!) MPEX commands you've typed, so MPEX HOOKed programs can save,
%REDO, %LISTREDO, and %DO up to the last 1000 commands you've typed inside
them.  This doesn't just mean that you can redo only MPEX commands you've typed
-- it means that you can redo ANY input you've entered.  For instance, you
might say:

   %QUERY.PUB.VESOFT;LIB=P
   ...
   >FIND PRICE>100 AND STATE<>"CA" AND NUM-UNITS<10 AND &
   >>    SHIP-CODE="XX"
   172 ENTRIES FOUND
   >REPORT
   >>D,CUST-NAME,30;D,PRICE,50;D,NUM-UNITS,70;end
   >,,
   ...
   129) FIND PRICE>100 AND STATE<>"CA" AND NUM-UNITS<10 AND &
   130)      SHIP-CODE="XX"
   131) REPORT
   >>D,CUST-NAME,30;D,PRICE,50;D,NUM-UNITS,70;end

As you see, the saved command history includes all the input you've typed to
QUERY -- the FIND command, its continuation, the REPORT command, the various
report sublines, etc.

All the features of MPEX's %LISTREDO, %REDO, and %DO are available in MPEX
HOOKed programs except:

   * Instead of typing just "LISTREDO", "REDO", or "DO", you must type
     ":LISTREDO", ":REDO", or ":DO" (note the ":").  This is done to avoid any
     confusion with subsystem commands.

     You can also use the ",,", ",", and ",." abbreviations, without any ":"
     prefix.  (In fact, if the program terminates when you enter a ":" -- like
     SPOOK5 does -- you'll HAVE to use the abbreviations.)

   * If you want to save the command history in a permanent file, you should
     make a file equation for "progname.REDO.VESOFT", where "progname" is the
     filename of the MPEX HOOKed program.  For instance, to save your EDITOR
     command history in the permanent file EDHIST, say

        :FILE EDITOR.REDO.VESOFT=EDHIST

One other important thing that you should know is that all subsystem input is
saved in the command history; also, all subsystem input is checked for a
leading "%" or ",".  There's no way for MPEX to know if EDITOR is prompting for
a command or, say, an /ADD line; therefore, all input that you enter in /ADD
mode will be saved in the command history together with all the EDITOR commands
you typed at the "/" prompt.

Also, if you type

   /ADD
     127.5   %ABC%

MPEX will see the "%" at the beginning of the input line and treat is an MPEX
command (even though the line was entered in /ADD mode); it'll try to execute
the MPEX command "ABC%", which will probably fail.  The same will happen if one
of your input lines starts with a ",".

One of the reasons we chose "%" and "," as identifying characters for MPEX
commands and redo commands is that it's unlikely you'll ever want to use them
for your own purposes.  If, however, you want to give the program true input
that starts with a "%" or a ",", you need to prefix the input with a space.

ACTIVATING THE FATHER PROCESS


___428
%%
If in response to any prompt of an MPEX HOOKed program you type the two
characters

   %%

then the MPEX HOOK facility will re-activate the father process of this MPEX
HOOKed program.  For instance, if you run MPEX HOOKed EDITOR out of MPEX, you
might say:

   :RUN MAIN.PUB.VESOFT
   ...
   %RUN EDITOR.PUB.VESOFT;LIB=P
   /TEXT MYFILE
   /...
   /%%
   %     << MPEX prompts you for input >>

Now, if you say %SHOWTREE, you'll see

   %SHOWTREE
   25    C.I.
     123   MPEX.PUB.VESOFT (active) [you are here]
       195   EDITOR.PUB.VESOFT

EDITOR.PUB.VESOFT still exists as a son process of MPEX -- if you now say

   %RUN EDITOR.PUB.VESOFT;LIB=P

or

   %RUN 195    << activate the PIN you saw in %SHOWTREE >>

or (if you have a UDC called ED that runs EDITOR.PUB.VESOFT),

   %ED

you'll be brought back into EDITOR, at exactly the same point that you left it.
Your file will still have been /TEXTed in, all the options you had set will
still be set, and, of course, the re-activation of EDITOR would take a lot less
time than re-running it from scratch would.

Of course, this will work equally well if you run a HOOKed program from any
advanced process handler (like MPEX itself) and then type "%%" in the HOOKed
program.  The purpose of the "%%" command is to make it easy for you to switch
from the HOOKed son process back to the father (which will later presumably be
able to re-activate the HOOKed son).

If you do run a program directly from the : prompt and then do a %% within it,
the MPEX HOOK will terminate the program rather than suspend it -- MPE doesn't
let us suspend processes that are run from the Command Interpreter.


VESOFTHOOKPPSONONLY_429
VESOFTHOOKPPSONONLY
If you want to, you can say

   :SETJCW VESOFTHOOKPPSONONLY=1

to indicate that "%%" (Percent Percent) can only be typed from TRUE son process
(i.e.  not a process run directly from the CI).  If you set this JCW and type
"%%" from a son of the CI, you'll get an error message; this might save you
from accidentally terminating a process that you only wanted to suspend.

BUILDING FILES IN OTHER ACCOUNTS

One of the nicest features of HOOKed programs is their ability to build files
in other accounts (assuming, of course, that you have SM capability).  For
instance, if you're logged on as MANAGER.SYS and run EDITOR.PUB.VESOFT, you'll
be able to say

   /KEEP MYFILE.DATA.AP

thus saving your work file in another account.  No need to log on into the AP
account -- no need even to /KEEP the file as some temporary file and then use
MPEX's %COPY command to copy the file into another account -- you can /KEEP
files in other accounts directly.

The same can be done with other HOOKed programs.  If you say

   :RUN FCOPY.PUB.VESOFT;LIB=P
   >FROM=MYFILEEB.DATA.AP;TO=MYFILEAS.DATA.AP;EBCDICIN;SUBSET=100;NEW
   >EXIT

then the HOOKed FCOPY will save the new file into the AP account (provided, of
course, that you have SM capability).

The only thing you need to worry about are programs that are "too smart for
their own good".  Some programs actually check to see if you're trying to
create a file in another account -- if you are, they don't even try to FCLOSE
the file (which is where the HOOK would intervene to allow the cross-account
save), but immediately print an error message.

For instance, if you try to /KEEP across account boundaries in EDITOR and the
/KEEP file already exists then EDITOR will print an error message (*71*KEEP
FILE MUST BE WITHIN LOG ON ACCOUNT).  In this case, you should

   * :PURGE the /KEEP file first

   * and then do the /KEEP.

If the /KEEP file DOESN'T already exist, EDITOR won't do the account check, and
everything will be OK.

Most programs don't do any special cross-account check, so you can make them
build files in other accounts with no difficulty:

   * FCOPY TO=;NEW files, for instance, can be built across account boundaries
     (provided, of course, that you're using a HOOKed FCOPY and have SM).

   * The contributed QUAD text editor can, when HOOKed and run with SM, /KEEP
     across account boundaries.

   * The BASIC subsystem, if HOOKed and run with SM, can >SAVE programs across
     account boundaries.

   * TDP, unfortunately, always checks for cross-account /KEEPs and prevents
     them before the HOOK can intervene.  Too bad.

MPEX HOOK PRESERVES ACDs IN EDITOR, TDP, etc.


MPEX_HOOK_preserves_ACDs_in_HOOKed_programs_430
MPEX HOOK preserves ACDs in HOOKed programs
If you're using Access Control Definitions (ACDs) on your files, you know that
when you /KEEP a file in EDITOR, TDP, or most other editors, the ACDs of the
file you've kept over are lost.  This is because a /KEEP purges the old file
and rebuilds it; when the old file is purged, its ACDs are destroyed, and the
new file is built without ACDs.

This can be a serious problem.  The person who does the /KEEP will most likely
forget to put the ACDs back on the file; even if he wants to, he might not know
what the ACDs were because once the /KEEP is done he can no longer see them.
(He'd have to remember to do a :LISTF ,-2 before every single /KEEP he does,
and an :ALTSEC;NEWACD= -- specifying every single pair! -- afterwards.)

What is most likely to happen this way is that, very soon, all the files that
you normally edit will lose their ACDs and all the additional security that
ACDs give them.

Naturally, we wouldn't be telling you this horror story if we didn't have a
solution up our sleeve.  All HOOKed programs will automatically preserve the
ACDs of any file that they purge and then re-build (which is exactly what a
/KEEP does).  To be precise, every time the program purges a file the HOOK
remembers that file's ACD; if the next file the program saves has the same name
as the just-purged file, the HOOK will impose that saved ACD on the new file.

Thus, if you do an EDITOR /KEEP, EDITOR will first purge the old file (at which
point HOOK will save the old file's ACD) and then save the new file with the
same name as the just-purged old file (at which point HOOK will put that saved
ACD onto the new file).

Note that the ACD that's saved is the ACD of the file purged by the /KEEP, not
the ACD of the file that was /TEXTed.  If you say:

   /TEXT A
   ...
   /KEEP B
   OK TO PURGE B? YES

then the new file B will have the same ACD as the old file B, not the same ACD
as A.

This is all done for you transparently -- no need to specify any special
keywords or options; whenever HOOK senses a purge followed by a save under the
same name, it will retain the file's ACD.

If for some reason you don't want to preserve a particular file's ACD, you can
always do an :ALTSEC ;DELACD of the file.  If you feel that you NEVER want the
HOOK to preserve ACDs for you, you should say


VESOFTHOOKNOKEEPACD_431
VESOFTHOOKNOKEEPACD

   :SETJCW VESOFTHOOKNOKEEPACD=1

before running the HOOKed program.  This will tell the HOOK to do nothing about
ACDs, which would normally mean that the programs will be allowed to throw away
ACDs at /KEEP time like they normally do.

Note that it is possible that some programs might not delete and rebuild files
in the way that the HOOK expects.  (For instance, if the program purges the old
file using the :PURGE command rather than using FCLOSE disposition 4, or if the
program builds the new file under a different name and then :RENAMEs it.) In
these cases, the HOOK might not be able to preserve the ACD because it won't
really know exactly what the program is doing.

We've tested the "keep ACD" feature in EDITOR and TDP.  Feel free to try it in
other programs; however, it is possible that the HOOK might not be able to
properly preserve ACDs for them.

HOW TO %HOOK A PROGRAM


HOOKing_programs__432
HOOKing programs
Some programs are HOOKed by VESOFT at installation time (EDITOR, QUERY).  To
"HOOK" other programs, just execute the MPEX command

   %HOOK progname

(To do this, you must have SM capability or be logged on into the VESOFT
account.)

Whenever you get a new version of a HOOKed program -- for example, a new
version of EDITOR.PUB.SYS from HP -- you should "re-HOOK" it.  For example,

   %HOOK EDITOR.PUB.SYS
   %HOOK QUERY.PUB.SYS

Or, you might say

   :RUN STREAMX.PUB.VESOFT
   Enter filename: MPEXHOOK.JOB.VESOFT
   Name of program to HOOK (if any)? EDITOR.PUB.SYS
   Name of program to HOOK (if any)? QUERY.PUB.SYS
   Name of program to HOOK (if any)? MYFILE.MYGROUP.MYACCT
   Name of program to HOOK (if any)?
     #J123

MPEXHOOK.JOB.VESOFT is a STREAMX job stream that can do the HOOKing for you.

HOW TO RUN A %HOOKed PROGRAM


MPE_V_and_MPE_iX_differences__MPEX_HOOK_433
MPE/V and MPE/iX differences: MPEX HOOK
To run "HOOKed" programs on MPE/V systems, or "HOOKed" Compatibility Mode
programs on MPE/iX systems, simply

      :RUN program.PUB.VESOFT;LIB=P


VEPROC_JOB_VESOFT_434
VEPROC.JOB.VESOFT
To run "HOOKed" Native Mode programs on MPE/iX systems, you will also need to
add the VESOFT procedures used by "HOOKed" programs to your system segmented
library, SL.PUB.SYS.  These procedures are kept in the USL file
VEPROCU.PUB.VESOFT, and can be added to the system SL by streaming the job
stream VEPROC.JOB.VESOFT.  (It's a simple, non-privileged procedure, so there's
no problem adding it to the system SL -- just re-stream VEPROC.JOB.VESOFT
whenever you do a system update.)

Note: VEPROC also adds the VECMMND, VEOPEN, and VECHECKLOGON procedures to the
system SL.  See "What If Your Program Does a :STREAM Programmatically (With The
COMMAND Intrinsic)?" in Batch Access Security, "Installing VEOPEN" in Database
Security, and "Checking SECURITY Logons From Within Your Program" in Logon
Security in the SECURITY User Manual for more details.

After adding the segments to SL.PUB.SYS, simply

      :RUN program.PUB.VESOFT;LIB=P

or

      :RUN program.PUB.VESOFT;XL="MPEXHKNL.PUB.VESOFT"

(the latter is especially useful if the program already has an XL list it must
be run with; generally, MPEXHKNL.PUB.VESOFT should be added to the end of the
list).

To make it easier to invoke the "HOOKed" programs, you may want to set the
MPEXUDC.PUB.VESOFT file system-wide.


MPEX_process_handling__435
MPEX process handling

MPEX can be a powerful process-handling environment.  Not only can you run
programs from within MPEX, but you can also:

   * Manage suspended programs, programs that suspend before re-activating MPEX
     instead of terminating.  STREAMX is a good example of such program, as are
     all MPEX HOOKed programs (in which "%%" is a suspend command).

   * Run son processes and pass them input -- without having to build a special
     ;STDIN= file!

   * Press [BREAK] and resume MPEX rather than aborting the entire MPEX process
     tree.

   * Use additional new MPEX :RUN command keywords, such as ;GOON and ;PRI=.

These features can be quite useful both in day-to-day work (e.g.  you can
easily jump from SPOOK5 to MPEX to EDITOR to QUERY without going through the
overhead of constantly re-CREATEing each son process) and for very
sophisticated "MPEX programming" constructs.

MANAGING SUSPENDED SON PROCESSES

Normally, when you run a program (from within MPEX, MPE, or any other program)
and then exit it, the son process (the program being run) dies.  It closes all
its files, forgets all its state information, and terminates.  If you want to
re-run the program, you have to re-run it from the beginning (which can take a
good deal of computer resources).

Some programs are smarter than that.  Take, for instance, SPOOK5.  If you say
(from MPEX):

   %SPOOK5
   SPOOK5 G.03.00  (C) HEWLETT-PACKARD CO., 1983
   > ...  do some work ...
   > EXIT
   %

you'll be back in MPEX as soon as you type the "> EXIT".  HOWEVER, the SPOOK5
son process won't actually be dead -- it'll only be SUSPENDED.

Now, when you again (from the same MPEX session) say:

   %SPOOK5

SPOOK5 will simply respond

   >

As you see, SPOOK5 doesn't print a header because it's not really being
re-:RUN.  Rather, it's being reactivated, a much quicker and more
resource-efficient operation.  Your current spool file is still >TEXTed, your
current line number is still unchanged, your current >MODE settings are the
same as they were when you >EXITed SPOOK5 before.

   In fact, if we type

   > EXIT

again in our suspended SPOOK5 son, we'll be back at MPEX.  Now, we might say:

   %SHOWTREE
   27    C.I.
     79    MPEX.PUB.VESOFT (active) [you are here]
       119   SPOOK5.PUB.SYS

This shows you that your MPEX process has a suspended son; in fact, given the
number on the left (the PIN, in our case 119 for SPOOK5), we can say

   %RUN 119
   >

to reactivate SPOOK5.

HOOKED PROGRAMS

This can be particularly useful when you're running "HOOKed" programs, programs
that have been modified (see the MPEX HOOK chapter) to honor MPEX commands, the
multi-line REDO facility, etc.

One of the things that every HOOKed program (e.g.  EDITOR.PUB.VESOFT,
QUERY.PUB.VESOFT, etc.) can do is suspend and re-activate the father process
whenever you type a "%%".  For instance, you might say:

   %RUN EDITOR.PUB.VESOFT;LIB=P
   /TEXT MYFILE
   ...
   /%%
   %

The "%%" typed at the "/" prompt -- essentially a new EDITOR command
implemented for you by the HOOK -- causes MPEX to be re-activated.  If you do a
%SHOWTREE now, you'll see:

   %SHOWTREE
   25    C.I.
     79    MPEX.PUB.VESOFT (active) [you are here]
       106   EDITOR.PUB.VESOFT

EDITOR.PUB.VESOFT still exists as a son process, with exactly the same /TEXTed
file, current line pointer, /SET command settings, etc.  Now, if you say

   %RUN EDITOR.PUB.VESOFT;LIB=P
   /

the EDITOR son process will be re-activated (in a fraction of a second), and
you'll be back where you were when you typed the "%%".

The key here is that EDITOR (and QUERY and FCOPY and KSAMUTIL and so on) don't
normally suspend -- if you enter EXIT in any one of them, they'll terminate
altogether.  It's the MPEX HOOK that implements the new "%%" command which
allows them to suspend instead of terminating.

A CAUTIONARY NOTE

We think that the ability to manage suspended son processes can be very useful;
however, it might sometimes surprise you (especially at first).  For instance,
if you say

   %SPOOK5
   > T 123
   > EXIT
   %

you must remember that SPOOK5 hasn't actually terminated, but has only
suspended.  Therefore, spool file #O123 is still locked by SPOOK5, and won't be
printable or deletable until you either >TEXT in a different spool file or
terminate the SPOOK5 son process.

The same may be said of the other suspendable programs, too.  If you say

   %QUERY.PUB.VESOFT;LIB=P;LIB=P
   >BASE=MYBASE
   ...
   >FIND ...
   >%%

QUERY will still be alive, MYBASE will still be opened, and whatever locks
QUERY may hold will still be held (which is, of course, what
suspending-instead-of-terminating is all about).  To terminate QUERY, you
should say either

   %QUERY.PUB.VESOFT;LIB=P;LIB=P
   >EXIT
   %

(since QUERY's >EXIT command does indeed terminate), or

   %KILL QUERY.PUB.VESOFT

MPEX's %KILL command (documented elsewhere in this manual) kills the son
process whose name you specify.

PASSING INPUT TO SON PROCESSES


INPUT__436
INPUT=

MPE's :RUN ;STDIN= lets you run a program with its $STDIN redirected to a disc
file.  But what if you don't want to build a disc file? What if you want to
have a UDC such as:

   ERASEDB !DBNAME
   RUN DBUTIL.PUB.SYS,ERASE

that will erase a database? You want to take the database name from the !DBNAME
UDC parameter, but DBUTIL.PUB.SYS,ERASE will prompt you for the database name.
You could :RUN DBUTIL.PUB.SYS,ERASE;STDIN=, but what will you use for the
;STDIN= file? Surely you don't want to have one ;STDIN= disc file for each
database you might want to erase!

MPEX solves this problem by implementing a new %RUN command parameter called
;INPUT=.  (Also, see commands %RUNCREATE, %RUNINPUT, and %RUNACTIVATE).  In the
above example, you could simply say

   ERASEDB !DBNAME
   RUN DBUTIL.PUB.SYS,ERASE;INPUT="!DBNAME"

MPEX will take the ;INPUT= parameter, write it to a special temporary file, and
then RUN DBUTIL.PUB.SYS with $STDIN redirected to that temporary file.

You can use the same construct for feeding multiple input lines -- you have
more than one ;INPUT= parameter on the same command, and each one will be
written to the temporary $STDIN file in turn.

For instance, a simplified version of MPEX's %EDIT command might have been
implemented as follows:

   PARM FILESET, CMD
   REPEAT
     ECHO -----Editing !MPEXCURRENTFILE
     CONTINUE
     RUN EDITOR.PUB.SYS;INPUT="TEXT !MPEXCURRENTFILE";INPUT="!CMD";&
                        INPUT="KEEP";INPUT="EXIT"
   FORFILES !FILESET

(see the %REPEAT ...  %FORFILES documentation for more details).

This runs EDITOR.PUB.SYS with ;STDIN= redirected to a temporary file that
contains the lines:

   * "TEXT filename", where filename is the name of the current file;

   * "cmd", where cmd is the EDITOR command being executed;

   * "KEEP", to keep the changed file back;

   * "EXIT", to get out of EDITOR.

If we didn't have ;INPUT=, we really couldn't do this sort of thing, since the
;STDIN= file to be passed to EDITOR changes from file to file.


INMSG_437
INMSG
One related feature that we provide is the ;INMSG keyword.  This merely tells
MPEX that the temporary file that contains the ;INPUT= lines is to be a message
file rather than a standard-format file.

Why would you want to do this? Well, say that you want to have a son process
that you keep suspended and "feed" commands to.  You might run it with
;INPUT="xxx";INMSG, and then keep re-activating it, passing more ;INPUT="xxx"
lines through this temporary message file.

A good example of this might be a UDC such as:

   SPOOKCMD !CMD
   RUN SPOOK5.PUB.SYS;INPUT="!CMD";INPUT="EXIT";INMSG

Now, if you say

   %SPOOKCMD "TEXT #O1234"

MPEX will create a SPOOK5 son process, pass it the command "TEXT #O1234", and
then pass it an >EXIT command which will re-activate MPEX.  Now, you have a
suspended SPOOK5 son process with a >TEXTed file; you may now say:

   %SPOOKCMD "L 1/20"

and the SPOOK5 son process will be activated and passed the "L 1/20" command --
it'll list the first twenty lines of #O1234 and then (because of the
INPUT="EXIT") re-activate MPEX.

As you see, you can now execute SPOOK5 commands from within MPEX much like you
could execute MPE commands from within EDITOR -- just prefix the SPOOK5 command
with "SPOOKCMD" and it'll be executed by the SPOOK5 son process.

:WAKE, MPEX's IMPROVEMENT TO [BREAK] AND :ABORT/:RESUME


WAKEUP_PUB_VESOFT_438
WAKEUP.PUB.VESOFT


_ABORT__RESUME_in_MPEX__439
:ABORT/:RESUME in MPEX

One of the problems with process handling is [BREAK]ing and :ABORTing.  If you
press [BREAK] and do an :ABORT, the entire process tree will be killed (a
phenomenon we call "mass processide").

If you run MPEX, run another program that gets into an infinite loop, press
[BREAK], and do an :ABORT, everything will be killed -- the program, MPEX,
whatever other son processes MPEX might have, and all of their son processes.

What's the solution? Well, one solution is not to run programs that go into
infinite loops...

Another, more practical alternative involves our WAKEUP program.  To use it,
you need to do two things:

   * :SETCATALOG WAKEUDC.PUB.VESOFT for your user, account (or even the entire
     system).  This defines a UDC called :WAKE that can be used in place of
     :ABORT (more about that later).

   * %WAKEUP.PUB.VESOFT in your MPEX session.  We suggest that you put this
     into your MPEXMGR, MPEXMGR.PUB, or MPEXMGR.PUB.VESOFT file.

Now, say that you enter:

   :RUN MAIN.PUB.VESOFT
   ...
   %INFLOOP.TEST
   << program branches to never-never-land...  >>

Now, instead of saying [BREAK] and :ABORT, you say

   [BREAK]
   :WAKE
   %

The :WAKE command has awakened the MPEX process (that's why you get the "%").
The INFLOOP.TEST process is still around:

   %SHOWTREE
   25    C.I.
     79    MPEX.PUB.VESOFT (active) [you are here]
       54    WAKEUP.PUB.VESOFT (active)
       106   EDITOR.PUB.VESOFT
       126   INFLOOP.TEST.DEV (active)

As you can see, INFLOOP.TEST.DEV is still active, chugging right along.  You
can either let it go (in which case it'll proceed just as if it were run with
;GOON -- see below), or say

   %KILL INFLOOP.TEST.DEV

or

   %KILL 126

The important thing to remember is that for [BREAK]/:WAKE to work, you must
have done a %WAKEUP.PUB.VESOFT in your MPEX session (as we said, preferably in
one of your MPEXMGR files) AND you must have a :WAKE UDC set for you.  WAKEUP
acts as a sort of "monitor" that's asleep, but can be awakened by the :WAKE
command -- when the :WAKE is done, WAKEUP is triggered, and it re-activates
MPEX (which is suspended waiting for its infinite-loop son to stop).

Naturally, there's no need for the son to be actually in an infinite loop.  It
could just be taking a long time doing something you don't want to do -- doing
a [BREAK], :WAKE, and then a %KILL can stop it.

The only thing you have to worry about is a son process that reads input from a
terminal.  When you do a [BREAK] and a :WAKE, MPEX is awakened, but the son
process remains active -- now, both MPEX and the son process are asking for
terminal input at the same time.  In this case, the first %KILL you type might
very well be read by the son process rather than by MPEX.  The son process will
probably just reject this, and prompt for input again -- keep entering %KILLs
until one of them will be read by MPEX.  (This is just the way MPE works when
two or more processes have simultaneous reads pending on a terminal.)

%RUN ;PRI=


PRI__440
PRI=

The ;PRI= keyword of the %RUN command lets you indicate the priority with which
you want the son process to run (CS, DS, or ES).  For instance, if you want to
run some big CPU-hog report, you could say:

   %RUN OINKOINK;PRI=ES

The son process OINKOINK will now run in the ES queue, and you'll get that
feeling of virtue for not slowing down other users too much.

%RUN ;STDIN=/;STDLIST=


STDIN__441
STDIN=


STDLIST__442
STDLIST=

MPEX's %RUN command has ;STDIN= and ;STDLIST= keywords just like MPE's :RUN
command does.  However, MPEX's ;STDIN= and ;STDLIST= need not be just filenames
-- they can include an entire :FILE-equation (except for the word "FILE"), e.g.

   %RUN MYPROG;STDIN="MYMSG,OLDTEMP;REC=,,F;DEL";&
               STDLIST="OUTFILE,OLD;SHR;GMULTI"

which is identical to

   %FILE TEMPIN=MYMSG,OLDTEMP;REC=,,F;DEL
   %FILE PERMOUT=OUTFILE,OLD;SHR;GMULTI
   %RUN MYPROG;STDIN=*TEMPIN;STDLIST=*PERMOUT

The same thing, but with the extended ;STDIN= and ;STDLIST= keywords you can
save yourself a :FILE-equation or two.

%RUN ;GOON


GOON_443
GOON

The ;GOON keyword (which means "go on") merely says that the son process is to
be run but MPEX should not be suspended.  For instance, say that you have a big
task (that requires no terminal input or output!) that you want to do in your
session, but you don't want to lock up your terminal.  You can say:

   %RUN BIGPROG;GOON

and have BIGPROG run as a son process while you keep doing whatever you want to
be doing in MPEX.  Watch out:

   * If BIGPROG does terminal output, you might get its output interspersed
     with whatever other output you're getting from MPEX or another son
     process.

   * If BIGPROG does terminal input, you might have it prompt for input at the
     same time as MPEX or another son process is prompting -- this can be very
     confusing, since you won't know which program will actually get the input
     line you type.

To be perfectly frank, the ;GOON keyword is useful rather infrequently, mostly
in sophisticated MPEX programming situations.  If you do use it, you might want
to also use the ;NOACTSONTERM keyword (see the %RUN command documentation for
more information).

%RUN ;NOACTIVATE, ;NEW, and ;KILL


NOACTIVATE_444
NOACTIVATE


NEW_445
NEW


KILL_446
KILL

These three %RUN command keywords govern how the son process is to be started
and/or terminated:

   * If you use ;NOACTIVATE, the son process will be CREATEd but not ACTIVATEd.

   * If you use ;NEW, the son process will always be CREATEd, even if a process
     with this name already exists.

   * If you use ;KILL, if the son process suspends instead of terminating, it
     will be KILLed.

These keywords are usually used for sophisticated MPEX programming
applications.  For instance, say that you want to have a UDC or command file
that runs SPOOK5, executes a few commands, and gets back to MPEX.  It might
look something like:

   SPOOKLIST !SPOOLFILENUM
   RUN SPOOK5.PUB.SYS;INPUT="TEXT !SPOOLFILENUM";INPUT="LIST ALL";&
                      INPUT="EXIT"

-- it'll run SPOOK5, >TEXT in the spool file you want, >LIST it, and then >EXIT
back to MPEX.

However, what if you already have a SPOOK5.PUB.SYS son process? You certainly
don't want to re-activate it, which is what the %RUN command would normally do
-- therefore, you say:

   SPOOKLIST !SPOOLFILENUM
   RUN SPOOK5.PUB.SYS;NEW;INPUT="TEXT !SPOOLFILENUM";&
                          INPUT="LIST ALL";INPUT="EXIT"

The ;NEW keyword will guarantee that a new SPOOK5 son process will be created.
However, now the SPOOK5 son is still alive, since the >EXIT command has only
suspended it, not terminated it.  You might say:

   SPOOKLIST !SPOOLFILENUM
   RUN SPOOK5.PUB.SYS;NEW;INPUT="TEXT !SPOOLFILENUM";&
                          INPUT="LIST ALL";INPUT="EXIT";KILL

to make sure that MPEX kills the son process after it's done.  (You might also
have said INPUT="QUIT" instead of INPUT="EXIT", telling SPOOK5 to execute the
>QUIT command, which forces a termination.)

In most cases you will probably find it more convenient to use the %RUNCREATE,
%RUNINPUT, and %RUNACTIVATE commands (documented earlier in this manual) rather
than ;NOACTIVATE, ;NEW, and ;KILL.

THE MPEXPIN JCW


MPEXPIN_447
MPEXPIN

One other feature that can be useful for fancy MPEX process handling
applications: whenever MPEX runs a son that suspends, MPEX will set the JCW
called "MPEXPIN" to the PIN of that son.  You can then save that value in some
other JCW, and then use it to re-activate or kill that son process, e.g.

   %RUN SPOOK5.PUB.SYS;NOACTIVATE
   %SETJCW SPOOKPIN=MPEXPIN
   ...
   %RUN !SPOOKPIN
   ...
   %KILL !SPOOKPIN

If you use MPEXPIN, you might also find the SONALIVE(PIN) function to be handy
-- it returns true if the son process with the given PIN is still alive.


MPEX_and_your_system_security__448
MPEX and your system security

Before we go any further, let us point out one of the fundamental principles of
MPEX:

MPEX IN NO WAY DIMINISHES YOUR SYSTEM SECURITY.

MPEX might make some things easier for people to do, but it'll never let
anybody do anything to a file that they wouldn't be entitled to do without
MPEX.

In fact, MPEX can greatly improve your system security by letting you easily
%SECURE filesets, find released files, find privileged programs, and so on.

REMOVING "CREATOR-ONLY" RESTRICTIONS


Security__removing_creator_only_restrictions_449
Security: removing creator-only restrictions


Security___RELEASE_450
Security: %RELEASE


Security___SECURE_451
Security: %SECURE


Security___RENAME_452
Security: %RENAME


Security___ALTSEC_453
Security: %ALTSEC

MPEX removes "creator-only" restrictions for the %RELEASE, %SECURE, %RENAME,
and %ALTSEC commands.

In MPE, you can't :RELEASE, :SECURE, :RENAME, or :ALTSEC a file unless you are
its creator.  You might have full access to it -- be able to copy it and purge
it -- but not be able to :RENAME it.  This struck us as a rather inconvenient
feature, one that didn't add anything to your system security (why should, say,
an account manager be prohibited from :RENAMEing a file in his own account).
Therefore, our rule is different:

   * Anybody who has READ, WRITE and EXECUTE access to a file can %RELEASE,
     %SECURE, %RENAME, or %ALTSEC it.

This is, of course, in no way a security violation.  Remember, somebody with
READ, WRITE, and EXECUTE access to a file can already do whatever he please to
it, from purging it to changing it to copying it.  It only makes much more
convenient something that somebody could always do the hard way.

COPYING FILES INTO OTHER ACCOUNTS


Security__copying_files_into_other_accounts_454
Security: copying files into other accounts


Security___COPY_455
Security: %COPY

Another thing that we allow is

   * We let anybody with "SM" capability copy files into other accounts.

Standard MPE security forbids ANYBODY -- even MANAGER.SYS! -- from building
files in other accounts.  We think that this makes no sense; if you have SM,
you could always log on to the target account, do the copy (possibly after
:RELEASEing the original file to make it accessible), and log back on to
wherever you were before.

But why make the system manager do this? MPEX lets him %COPY files into other
accounts (also, MPEX HOOKed programs allow SM users to build files in other
accounts, so HOOKed EDITOR for instance allows cross-account /KEEPs).  No
security violation, but a great convenience!

WORKING ON DATABASES


Security__databases_456
Security: databases


Security__IMAGE_457
Security: IMAGE

MPEX lets you do several things to databases:

   * %COPY them.
   * %RENAME them.
   * %ALTFILE ;DEV=xxx them (to move them from one disc to another).
   * %RELEASE them.
   * %SECURE them.
   * %ALTSEC them.
   * %PURGE them.

Naturally, file system security rules are not enough for checking database
access -- many databases are >>RELEASEd and count on their privileged file
codes and IMAGE security to protect them.

The rule that MPEX uses is that:

   * ONLY
       - the database's creator,
       - the account manager of the database's account, or
       - the system manager

can execute any of the above commands against a database file.

SPOOL FILES


Security__spool_files_458
Security: spool files

Normal MPE :ALTSPOOLFILE and :DELETESPOOLFILE are available only to the console
operator and people who are :ALLOWed those commands.  MPEX's %ALTSPOOLFILE and
%DELETESPOOLFILE can be done:

   * by the spool file's creator,
   * by the account manager of the spool file,
   * by the system manager, or
   * by a user with "OP" capability

These restrictions are exactly those that SPOOK5 imposes for its >PURGE and
>ALTER commands.

LOCKWORDS


Security__Lockwords_459
Security: Lockwords

In MPE, whenever you want to access a lockworded file, you must specify the
lockword (even if you're SM or AM and can figure out with :LISTF ,-1).  This is
no big deal on MPE's single-file commands, but say that you're doing a

   %COPY @.@.AP, @.@.APNEW

-- you certainly don't want to be prompted for the lockword of each lockworded
file (or have the %COPY of that file fail if it's done in batch).

MPEX's rule on this is rather straightforward:

   * If you have SM, MPEX will automatically supply lockwords on all lockworded
     files in the source fileset.

   * If you have AM, MPEX will automatically supply lockwords on all lockworded
     files in the source fileset as long as the file is in your own account
     (files in other accounts won't have lockwords automatically supplied).

   * If you specify a lockword on the source fileset, e.g.

        %COPY @/FOO.@.AP, @.@.APNEW

     then MPEX will automatically supply the lockword "FOO" on all lockworded
     files in the source fileset that have that lockword.  In other words,
     non-lockworded files will be handled OK, and so will be those that have
     the lockword "FOO" -- however, a file with any other lockword won't have
     it automatically supplied (and you'll be prompted for it when the time
     comes).

   * If none of the above is true, the lockword will not be automatically
     supplied, which simply means that you'll be prompted for it just as you
     would in MPE (in batch, you'll get a lockword violation error).

This solution maximizes both ease-of-use and security -- you don't lose any
security since people with SM or AM can figure out the file lockword anyway
(using :LISTF ,-1).

One thing that you must keep in mind with lockwords is that unless you
explicitly specify a lockword in a target file (e.g.  the second parameter on a
%COPY or a %RENAME), the target file will be built without a lockword.

For instance, the

   %COPY @.@.AP, @.@.APNEW

will build the APNEW files without lockwords.  This is done for MPE
compatibility -- if in MPE you say

   :RENAME X/LOCK,Y

or

   :FCOPY FROM=X/LOCK; TO=Y; NEW

then the new file will be created without a lockword -- therefore, the %RENAME,
%FCOPY, and %COPY commands were made to act the same way.


Lockwords__preserving_them_on__COPY__FCOPY__RENAME_460
Lockwords: preserving them on %COPY/%FCOPY/%RENAME
What if you want to preserve the lockword? No problem! Just say

   %COPY @.@.AP, @/=.@.AP

As you see, the target fileset (@/=.@.AP) was specified with a lockword of "=".
The "=" wildcard (see "Target Filesets" in the MPEX Filesets chapter) tells
MPEX to make that part of the target file be identical to the corresponding
part of the source file; specifying an "=" in the lockword portion of a
filename indicates that the target lockword should be identical to the source
lockword.

Naturally, the same thing will work in %RENAME and %FCOPY commands.


GOD____gives_SM_capability_461
GOD -- gives SM capability

Say that you are the system manager and have to log on as a normal user to do
some trouble-shooting; or, you need to log on under a particular user ID to run
one of your programs.  Whenever you log on as a non-SM user, many of the things
that you are used to doing as SM no longer work.  You can no longer access the
files that you need to or run the programs that you need to; you can no longer
:RUN some programs with the ;DEBUG parameter.  The operating system looks at
your logon ID, sees that this user doesn't have SM capability, and forbids you
any SM-level operation.  What MPE doesn't realize is that you (personally)
really are the system manager -- you just had to log on as a user who doesn't
have SM capability.

VESOFT's MPEX product includes a program called GOD.PUB.VESOFT (which you
should, of course, keep under a lockword) that temporarily grants you all the
capabilities and all the :ALLOWs on the system.  This way, if the system
manager has to log on as a "plain vanilla" user, he can run GOD and be the
system manager again, regardless of his logon.  (The user ID's capabilities are
not permanently changed -- when you next log on as this user ID, it'll have the
same capabilities that it did before; the system manager can also run a program
called MORTAL.PUB.VESOFT to return to his pre-GOD state without having to log
off.)

Since GOD has a lockword (whenever we install GOD on a system that didn't have
it before, we actually assign it a random lockword!), only the person who knows
the lockword (which should only be the system manager) can run it.

GOD can also be useful if some job stream that you have needs to acquire some
special capability or :ALLOW -- you can have it do a !RUN GOD.PUB.VESOFT,
perform the operation that needs the capability or :ALLOW, and then !RUN
MORTAL.PUB.VESOFT.  Using STREAMX's $NOPASS keyword, you can even do this
without having to embed the GOD lockword into the job stream.

GOD is not just a great convenience for the system manager; it can actually
ENHANCE your system security.  If you don't use GOD, then you will inevitably
have more :RELEASEd files, weaker group and account security, and more global
:ALLOWs than necessary.  Say that the system manager finds that he often has to
do a :REPLY or a :STARTSPOOL when logged on as various user IDs -- without GOD,
he'll be quite likely to :ALLOW these commands globally since there would
otherwise be no way for him to access these commands.  If he has GOD, he can
avoid :ALLOWing these commands because he will always have them available (if
he knows the GOD lockword).  Similarly, if the system manager finds himself
needing various programs or data files when he logs on as non-SM users, he will
be tempted to :RELEASE these files or otherwise keep them less secure than they
should be.  If he uses GOD, he will always be able to access any file he needs
-- again, only if he knows the GOD lockword.

If you have SECURITY you can protect it even further -- see the
SECURITY User Manual chapter on Restricting Access To GOD.PUB.VESOFT.  In fact,
SECURITY provides a number of useful features (like $ALLOW, CHLOGON, and
WITHCAPS) that eliminate the need for GOD.PUB.VESOFT in most circumstances --
see the SECURITY User Manual for more details.


MORTAL____undoes_a_previous__GOD__operation__462
MORTAL -- undoes a previous "GOD" operation

MORTAL is a program which sets the capabilities of the user who runs it back to
their original state.  This program is usually run after GOD is run to bring
user's normal capabilities back (see "GOD" in this section of this manual):

   :RUN MORTAL.PUB.VESOFT

MORTAL can also be used any time you need to change user's capabilities, while
doing :ALTUSER; normally, the user must log back on to the system to have the
new capabilities.  Instead, he can run MORTAL to transfer the capabilities from
the system tables to your session's capability area in the stack.


VEMODIFY____line_editing_made_easier__463
VEMODIFY -- line editing made easier

VEMODIFY is a VESOFT-written procedure that provides a
   ONE-PASS, VISUAL FIDELITY
line modification facility which is much easier to use than EDITOR's or TDP's
/MODIFY (or the MPE :REDO command's modification facility).  It may be used in:

   * An MPEX HOOKed EDITOR or TDP (using the /MV command).

   * MPEX's %REDOs (if the HPREDOVEMODIFY JCW is set).

   * :REDOs (or ','s) in any MPEX HOOKed program.

   * Your own EXPRESSION programs or command files by calling the VEMODIFY(...)
     function.

VEMODIFY's visual fidelity means that any modifications made to a line are
echoed immediately rather than echoed after you press [RETURN].  As you do the
modifications, VEMODIFY uses the power of your HP terminal to change the line
as it appears on your screen at the same time as the line is changed in
VEMODIFY's internal editing buffer.


Visual__REDO_extends_beyond_1_screen_line_464
Visual %REDO extends beyond 1 screen line
The VISUAL REDO facility allows you to edit a line up to 150 characters in
length.  Since this is longer than a single screen line (even in 132 column
mode), characters inserted in the first line will wrap-insert into the second
line, and characters deleted from the first will pull back characters from the
second line.

To use VEMODIFY in a HOOKed EDITOR, type

   /MV linerange     << e.g.  /MV 1/4 >>

after :RUN EDITOR.PUB.VESOFT;LIB=P.  To use it in MPEX's (and HOOKed programs')
REDO, say

   :SETJCW HPREDOVEMODIFY=1

before entering the program.

VEMODIFY displays the line to be modified for you and prompts for modifications
with the cursor right on top of the first character of the line.  Then, when
you type a printable character (e.g.  'B'), that character overwrites the one
beneath it or is inserted before the one beneath it; when you type an
unprintable character (e.g.  <control-B>, space, etc.), VEMODIFY considers it a
special command (see below).

Note that any unprintable control characters that were in the line when
VEMODIFY was called are echoed as '.'s; no new unprintable control characters
can be introduced into a line with VEMODIFY.  If you make a mistake (e.g.  type
a control character that VEMODIFY does not consider a command, backspace beyond
the first character in the line, etc.), VEMODIFY rejects your command and rings
the terminal's bell.

The user should press [RETURN] only once -- when the line modification is
completed!

CALLABLE VEMODIFY FUNCTION FOR EXPRESSION PROGRAMS AND COMMAND FILES


CALLABLE_VEMODIFY_FUNCTION_465
CALLABLE VEMODIFY FUNCTION


VEMODIFY_466
VEMODIFY

To use the VEMODIFY(...) function in your own expression program or command
files, pass the string you want the user to modify to the function and set the
result to a variable that contains the edited string.  For example, suppose you
want to "prompt" the user for some data, and you want to supply a default value
based upon what the user typed in the last time.  This is one way to accomplish
this:

   For a command file:

   %ECHO Please enter the destination for the report
   %SETVAR DEST VEMODIFY(SVAR('DEST','LP'))

   For an expression program:

   WRITELN ('Please enter the destination for the report');
   DEST := VEMODIFY(SVAR('DEST','LP'));

This displays the prompt string ("Please enter the destination...") and then
displays either the previous value of the variable DEST, or "LP" if DEST has
never been set.  The user will then be in modify mode and can change the value
for DEST as needed or simply press [RETURN] if all is well.

The VEMODIFY commands are:


VEMODIFY__Control_A__467
VEMODIFY: Control-A
Control-A  (Append)    Same as <control-L>.  Moves the cursor to the end of the
                   line, thus allowing you to append text to your line.


VEMODIFY__Control_B__468
VEMODIFY: Control-B

Control-B  (Before)    Same as <control-^>.  Enters Insert Character mode.  All
                   characters typed (until a [RETURN] or <control-T>) will be
                   inserted before the current character.


VEMODIFY__Control_C__469
VEMODIFY: Control-C

Control-C  (Case)      Changes the case of the current character -- upshifts it
                   if it is lower case, downshifts it if it is UPPERCASE.  Does
                   not affect non-alphabetic characters.


VEMODIFY__Control_D__470
VEMODIFY: Control-D

Control-D  (Delete)    Deletes the current character.  If at the end of line,
                   deletes the line's last character.


VEMODIFY__Control_E__471
VEMODIFY: Control-E

Control-E  (Erase)     Erases everything from the current cursor position to
                   the end of the line.


VEMODIFY__Control_F__472
VEMODIFY: Control-F

Control-F  (Find)      Must be followed by another character.  Finds the first
                   occurrence of that character after the current cursor
                   position,  i.e.  <control-F> followed by an 'A' moves the
                   cursor to the next 'A' in the line.  If the character is a
                   <control-W>, this function finds the first character of the
                   next word.  Also, if you type <control-F> <control-B> 'A',
                   VEMODIFY will find the second occurrence of 'A' after the
                   current character (B is the second letter of the alphabet);
                   similarly, typing <control-F> <control-C> 'A' will find the
                   third occurrence of 'A' after the current character, and so
                   on.


VEMODIFY__Control_G__473
VEMODIFY: Control-G

Control-G  (Goof)      Undoes all modifications made to this line.


VEMODIFY__Control_L__474
VEMODIFY: Control-L

Control-L  (Lengthen)  Same as <control-A>.  Useful when VEMODIFY is used on
                   system console where <control-A> is reserved.


VEMODIFY__Control_N__475
VEMODIFY: Control-N

Control-N  (Number)    Displays the line number of the current line.  After
                   this number has been displayed, pressing <control-N> again
                   will remove the line number.


VEMODIFY__Control_O__476
VEMODIFY: Control-O

Control-O  (Overwrite) Enters space overwrite mode.  In this mode, typing a
                   space causes the character beneath to be overwritten with a
                   space rather than just causing the cursor to move forward.
                   This mode is also initiated by typing any PRINTABLE
                   character, and is stopped with <control-T>.


VEMODIFY__Control_Q__477
VEMODIFY: Control-Q

Control-Q  (Question)  Displays this page of the manual, the "help" for
                   VEMODIFY.


VEMODIFY__Control_S__478
VEMODIFY: Control-S

Control-S  (Scan)      Same as <control-F>, but finds the first occurrence of
                   the character specified BEFORE the current cursor position.
                   Note that <control-S> <control-W> will find the first
                   character of the previous word.


VEMODIFY__Control_T__479
VEMODIFY: Control-T

Control-T  (Terminate) Terminates Character Insertion (<control-B>) mode and
                   Space Overwrite (<control-O>) mode.  Typing <control-T>
                   <control-D> causes the current line to be deleted.


VEMODIFY__Control_X__480
VEMODIFY: Control-X

Control-X  (cancel)    Redisplays the current state of this line and moves the
                   cursor back to column 1.


VEMODIFY__Control____481
VEMODIFY: Control-^

Control-^  (insert)    Same as <control-B>.  Useful when VEMODIFY is used on
                   system console where <control-B> is reserved.

" " (space)            Moves the cursor forward (default mode), blanks out the
                   current character (Space Overwrite mode), or inserts a blank
                   before the current character (Insert Character mode).

Printable Character    Overwrites the current character (Default mode) or is
                   inserted before the current character (Insert Character
                   mode).  Turns on Space Overwrite mode.

<backspace> key        Moves the cursor back one column.

<tab> key              Moves the cursor forward 10 columns.


ONLINE_NOTEPAD_482
ONLINE NOTEPAD


NOTEPADS__using_the___to_enter_a_note_483
NOTEPADS: using the ; to enter a note

Has this ever happened to you:
You're on the phone with a friend or client, they mention in passing that their
phone number has changed, and you suddenly discover that all of the pens on
your desk have mysteriously and simultaneously run out of ink.  After a bit of
coaxing and lots of furious scribbling on what you thought was a bit of scrap
paper (but turned out to be your last sheet of 20lb letterhead) you get the pen
working only to realize you never heard the new number...

MPEX has a new "notepad" feature that is literally a single keystroke away! Any
command line beginning with a semicolon (;) will be treated as a single line
"note" to be entered in a notepad file! Beginning a command line with two
semicolons will list or search the contents of the file.


NOTEPADS__changing_the_notepad_character__484
NOTEPADS: changing the notepad character
You can change what character MPEX recognizes as the "notepad character" by
setting the special variable MPEXPREFIXNOTE to either the ASCII value of a
character or the actual character itself.  In fact, you may be forced to set
this variable if you use an MPEXPREFIXDEF variable for the ";" character since
the MPEXPREFIXDEF character will override the notepad action.  See the section
of our manual regarding SPOONFEEDING for details on the MPEXPREFIXDEF
variables.

So when Joe says, "Hey, I've just been moved to a new department over in the
east wing of our complex, so starting next Thursday you can reach me at
555-1234", you simply type:

   %;JOE:PHONE (work): 555-1234

and MPEX immediately files this bit of information away safely and cleanly (and
you still have a sheet of letterhead available to write a letter congratulating
your client on his promotion).

Everything you type after the notepad character is written to a file along with
a date and time stamp.  When you list the file later, you can see when the
notes were made.  Since the time/date stamp takes about 20 characters to
display, you should limit your entries in the file to 50-60 characters to avoid
having the lines "wrap" when displayed.

MULTIPLE NOTEPADS -- A MINI-FILE CABINET


NOTEPADS__MULTIPLE_notepads_485
NOTEPADS: MULTIPLE notepads

You actually have access to 11 separate notepads -- your default notepad and
ten others numbered from 0 to 9.  If you precede the notepad character with a
number from 0 to 9, then the note will be written to the corresponding notepad.
(of course, "#;;" will list the contents of that particular notepad).

NOTEPADS -- NAMING


NOTEPADS__naming_using_VESOFTNOTEFILE_variable_486
NOTEPADS: naming using VESOFTNOTEFILE variable

How do we determine the name of your notepad? If you did not log on with a
session name, i.e.  you logged on simply as CLERK.OFFICE,MYGROUP, then we use a
file called VENOTE.MYGROUP.  (actually, it is "VENOTE?" where the "?" character
is replaced by the notepad number or blank for your default notepad).  If you
logged on with a session name, as in "BOB,MGR.DEV", then we use a file called
"BOB?.VENOTE.VESOFT".  Since we append a "?" character to the end of your
session name, and MPE limits file names to 8 characters, we only use the first
7 characters of your session name so that we don't generate an error trying to
create a 9 character name.

Using your session name is great if every session name is unique (since you can
refer to the same notepad files regardless of where you log on) or if everyone
logs without a session name but in different groups (in which case the file
VENOTE? is built in each group), but what if everyone logs on as
"CLERK.OFFICE,PUB" or you have two users who log on with the session name of
"JOE"? In these cases, you should set a special variable, VESOFTNOTEFILE, to a
filename of your own choosing and MPEX will use that file for keeping notes.
Note that in order to use the multiple notepad feature, you must put a question
mark in as part of the filename.

SEARCHING AND PRINTING


NOTEPADS__Searching___printing_487
NOTEPADS: Searching & printing

By default:
   ;;         will print the entire contents of your standard notepad.
   ;;text     (without any wildcards) will do a caseless search for any lines
              containing that text, (;SEARCH=CL"text")
   ;;text     (with wildcards: @, ?, [...], etc.) will search for a match
              against the wildcarded argument.  (;SEARCH=R MATCHES "text")
   ;;.exp will search for the specific string expression.  (;SEARCH=exp)

Since we actually use our %PRINT command internally, you can use the ";;."
syntax to specify a search string and/or regular MPEX %PRINT parameters.  For
instance, to print the entire file to a printer, use ";;.;out=*lp".  To print
the file without stopping (on screen), use ";;.;page=0".  As these are
translated to ;SEARCH=;OUT=*LP and ;SEARCH=;PAGE=0, (the search argument is a
NULL) the ;SEARCH= keyword is effectively ignored.

By default, we apply the ;NUM parameter to the %PRINT command in order to
display line numbers (for editing, see below), if this causes lines to "wrap
around" your display, then you can add ;UNN to the command to avoid this
problem.

NOTEPAD EDITING: MODIFY & DELETE


NOTEPADS__editing_with___M_odify_____D_elete_488
NOTEPADS: editing with [;M]odify & [;D]elete

It should be fairly obvious that this feature is not intended to replace a
full-scale editor for maintaining a simple text file -- there are plenty of
editors already on the market available for such tasks.  Instead, this is
intended to be a simple, quick, extension to MPEX that allows for rapid entry
and retrieval of simple notes when it isn't convenient to grab a piece of paper
or run a different program.  However, just offering the ability to add and
subsequently find notes is not sufficient.  After all, information changes over
time, records need to be updated, and eventually the information become
obsolete and should be deleted.  Therefore, we also provide the ability to
modify lines and delete lines that are no longer needed.

Earlier we mentioned that listing the contents of a notepad with ";;" would, by
default, be numbered for "editing".  Entering ";M[number]" will modify the
specified line number and ";D[number]" will delete the specified note line.
The default for either of these options is the last note line entered.

The modify command makes use of our visual-redo facility if you have our JCW
set for this option, otherwise is uses the normal editor / command interpreter
editing commands.

At the moment, this is the extent of the editing capabilities available --
modifying incorrect lines (for instance, to correct the spelling of a
particular item or update the status of a project) and deleting lines no longer
deemed necessary (presumably, for tasks that have been completed).  If you find
that you must edit the file a bit more extensively, say for instance to add a
paragraph or two to a note, then you should use a regular editor to edit the
appropriate file (see the section on how the files are named).  One thing to be
aware of when editing a note file manually is that the date & time stamp area
of the file (the first 17 characters) cannot be "edited" using the ";M"
command.


MPEX_commands__489
MPEX commands

MPEX recognizes many different commands.  Some of them have no analog in MPE;
others are quite similar to normal MPE commands.  In general, whenever MPEX
prompts you (with a "%") for a command, you can type one of the following:

   * An ordinary MPE command, including commands such as %RUN, %EDITOR,
     %SHOWCATALOG, etc.

   * A UDC invocation.  (Note that normally the MPE/V COMMAND intrinsic doesn't
     let you execute UDCs -- we're rather proud to say that we were the first
     product [outside HP's Command Interpreter] that let you execute UDCs from
     within it.)

   * One of the special MPEX commands (listed below), such as %COBOL, %COPY,
     %INPUT, %SETVAR, etc.

   * One of the special MPEX commands that can handle filesets (%COBOL, %COPY,
     %EDIT, etc.), prefixed by a "?" -- this tells MPEX to prompt you Yes/No
     for each file in the fileset and execute the command only on those files
     for which you say "Yes".

   * Any command (MPE or MPEX) prefixed with a "$", indicating that the command
     is to be executed offline (in a batch job stream of its own).

   * The name of a program file (fully-qualified or not), which is then
     automatically :RUN; for instance, saying

        %DBUTIL

     will automatically do a :RUN DBUTIL.PUB.SYS even though you don't have
     such a UDC!

   * The name of a command file, an ordinary EDITOR file that contains a set of
     commands to be executed.  This is very similar to a UDC, but it doesn't
     have to be :SETCATALOGed -- just entering its filename causes it to be
     executed.

How does MPEX decide which one of these to do? Suppose you have both a program
and a UDC named FIBAR.  Should MPEX execute the UDC, or run the program?
Basically, MPEX follows the same rules as MPE/iX:

   * first look for a UDC;

   * next, see if the command is an MPEX command; if not,

   * see if the command is an MPE command;

   * finally, if none of the above is true, look for a program file or a
     command file matching the command name, execute that.

There are several things that can change this order:

   * if you precede the command with %XEQ, MPEX will look for a command file or
     program file, and if it doesn't find one, print an error;

   * if you precede the command with %RUN, MPEX will look for a program file,
     and if it doesn't find one, print an error;

   * if you precede the command with a ":", MPEX will not look for an MPEX
     command (but it will emulate MPE/iX commands on MPE/V systems);


__prefix__execute_MPEX_command_instead_of_a_UDC_with_the_same_name_490
! prefix: execute MPEX command instead of a UDC with the same name
   * if you precede the command with a "!", MPEX will not look for a UDC -- use
     this if you have a UDC with the same name as an MPEX command.  You can
     precede "!" with a "$" to execute the command "offline" (see "Batch
     Execution" in this manual).


VESOFTCONTINUENOSPACE_491
VESOFTCONTINUENOSPACE


__492
&
Just like in MPE, any MPEX command can be continued with an "&".  For
compatibility with MPE/V and older versions of MPEX, MPEX inserts a space
character in the command line in the position where the "&" was and includes
leading spaces on the continued line.  MPE/iX, however, does not include a
space for the "&" and strips leading spaces from the continued line.  If you
want to tell MPEX to use the MPE/iX behavior, you should set the variable
VESOFTCONTINUENOSPACE to 1 in your MPEXMGR.PUB.VESOFT file.

   %SETVAR VESOFTCONTINUENOSPACE 1

In addition (also like MPE), the length of the entire command is limited to 279
characters, after all variables and expressions within the command have been
"resolved" (see "Using MPEX Variables", in this manual).

The following are all examples of valid MPEX commands:

   %SHOWJOB JOB=@J

which executes the ordinary MPE command :SHOWJOB JOB=@J.

   %RUN MYPROG;LIB=G;PARM=17

which executes the MPE command :RUN MYPROG;LIB=G;PARM=17.  Although such a
      command can't normally be executed through the COMMAND intrinsic, MPEX
      can execute it nonetheless.

   %S J

which, if you have a UDC called :S, will invoke it with parameter "J".

   %DELETESPOOLFILE $STDLIST.@.@(SPOOL.OUTPRI<=3)

which will delete all the $STDLISTs in the system that have an output priority
      of 3 or less (for more information, see the %DELETESPOOLFILE command
      description in this manual).

   %$COBOL AP@.SOURCE, AP@.PUB
   %$RUN MYPROG;LIB=G;PARM=17

which will execute the specified commands in batch jobs (one batch job for the
      COBOL command and one for the RUN command).  As you see, MPEX allows easy
      offline execution of either MPEX commands or normal MPE commands -- just
      prefix them with a "$".

   %DBUTIL

which will run the program DBUTIL.PUB.SYS.  Actually, it will (by default)

         - first try to run DBUTIL (in your logon group);

         - if it can't find DBUTIL, it'll try to run DBUTIL.PUB (in your logon
           account);

         - if it can't find DBUTIL or DBUTIL.PUB, it'll try to run
           DBUTIL.PUB.SYS.

      Thus, if you had a program called MYPROG in your own group and account,
      you could run it by simply saying

         %MYPROG

   %FROBOZZ 10, 20, 30

which will execute the commands in the file FROBOZZ (or FROBOZZ.PUB or
      FROBOZZ.PUB.SYS), passing to them as parameters 10, 20, and 30.  The file
      FROBOZZ might look like:

         PARM WIDGETS, GADGETS=33, FRAMASTATS, THINGAMABOBS=55
         BUILD XXFILE;TEMP;REC=![WIDGETS+GADGETS+FRAMASTATS]
         RUN TWIDDLE;PARM=!WIDGETS;INFO="G!GADGETS"
         RUN TWADDLE;PARM=!FRAMASTATS;INFO="XXX!THINGAMABOBS"
         PURGE XXFILE,TEMP

-- just like a UDC, except that instead of the header line "FROBOZZ WIDGETS,
      ...", the header says "PARM WIDGETS, ...".


_ABORTJOB_493
%ABORTJOB

Syntax:   %ABORTJOB userset
          [;NOVERIFY]
          [;QUIET]

Examples: %ABORTJOB @.AP-MGR.AP-RON,@.@
          %ABORTJOB #J1234+#J1235
          %ABORTJOB ONLINE-LDEV=!HPLDEVIN-LDEV=!HPCONSOLE
          %ABORTJOB QREPORT,@.@
          %ABORTJOB ACCESSING=CUST.DB.PROD
          %ABORTJOB #A10   (aborts a STREAMX scheduled job)
          %ABORTJOB @J&SCHED   (aborts only MPE-scheduled jobs)
          %ABORTJOB SCHED-@A


See_also_SEC_HELP_USERSET__494
See also SEC HELP USERSET


See_also_ACCESSING__User_attribute_by_typing__SEC_HELP_ACCESSING_495
See also ACCESSING= User attribute by typing %SEC HELP ACCESSING
The %ABORTJOB command is an enhanced version of MPE's :ABORTJOB command.  It
allows you to specify which jobs to abort using VESOFT usersets (see the
usersets section in the Logon Security chapter of the SECURITY User Manual).

By default, ABORTJOB will show the job numbers and logon IDs of all the jobs
that are to be aborted and then ask you if it's OK to abort them.  If you do
not reply "Y", the jobs will not be aborted.  This can help you avoid
accidentally aborting many jobs that you don't actually want to abort.

If you want to do the %ABORTJOB without prompting for verifications, just
append ";NOVERIFY" to the command, e.g.

     %ABORTJOB BATCH&EXEC;NOVERIFY

This will still show the numbers and logon IDs of the jobs that are being
processed.  If you used the ";QUIET" keyword instead, e.g.

     %ABORTJOB @.AP&WAIT;QUIET

then both the verification request and the job numbers/logon IDs will not be
displayed.

Note: for compatibility with MPE, if you specify a single job/session number
(e.g.  "%ABORTJOB #J1234") you will not be asked for verification, and the job
number/logon will not be displayed, just as if you had said ";QUIET".

ABORTJOB and STREAMX scheduled jobs


_ABORTJOB_and_STREAMX_scheduled_jobs_496
%ABORTJOB and STREAMX scheduled jobs

Our STREAMX product (part of SECURITY/3000) has the ability to schedule jobs
based upon a date, time, or event, with an option to repeat as needed.  These
jobs are shown by our %SEC SHOWSCHED command with a "#A" that specifies each
scheduled job.  For example, entering %ABORTJOB #A12 would abort scheduled job
#12 in our job scheduler.  Once a job is scheduled, it keeps the same #A number
until it is launched or aborted, or in other words, the %ABORTJOB command
doesn't change scheduled job numbers.

The %ABORTJOB command also supports our %SHOWJOB usersets of @J, @S, and @A.


_ABORTJOB_and_scheduled_jobs_497
%ABORTJOB and scheduled jobs
See the chapter on repeating jobs in the STREAMX section of the SECURITY manual
for more details.


_ALARM_498
%ALARM

Syntax:   %ALARM ["time|booleanexpression"], [message]
          [;TO= userset]|[;LOGON]|[;TERMINAL]|[;SESSION]
          [;NOHP]
          [;scheduleparms]
          [;CHECKEVERY=interval]
          [;REPEAT=DAILY|WEEKDAYS|list of days]
          [;WHEN=expression]
          [;WHENEVER=expression]

          %SHOWALARM
          [;ALL]
          [;FROM= mpeuserset]

          %DELETEALARM alarmnumber

Examples: %ALARM "11:45AM", Almost time for lunch!
          %ALARM "2:30PM", "Don't forget our meeting at 3:00";TO=@.DEV
          %ALARM 'JSCOUNT("REPORT1,BATCH.PROD")=0', REPORT1 is done!
          %ALARM 'JSCOUNT("BILL,@.@")>0', Bill has logged on!; &
                 CHECKEVERY=5
          %ALARM "HPJOBCOUNT>3", More than 3 jobs are logged on!; &
                 TO=LDEV=20
          %ALARM , FORBIN Project is due TODAY!; TO=TERMINAL; &
                 DATE=11/05/91; AT=9:00

          %SHOWALARM
          %SHOWALARM;ALL
          %SHOWALARM;FROM=@.DEV

          %DELETEALARM 1


AT__499
AT=


DAY__500
DAY=


DATE__501
DATE=


IN__502
IN=
The %ALARM command uses the BACKG background job (see the %BACKG command in
this manual for details) to send the specified message at some given future
time.  Alarms can be set by specifying:

   * the time-of-day;

   * a boolean expression (the message will be sent when the expression becomes
     TRUE);

   * MPE :STREAM-type scheduling parms (";AT=", ";DAY=", ";DATE=", or ";IN=").
     Note that these are entered as separate parameters and not within the
     first parameter.


TO_userset_503
TO=userset


LOGON_504
LOGON


SESSION_505
SESSION


TERMINAL_506
TERMINAL
By default, the message will be sent to your logon (i.e.  to the
"session,user.account,group" you were logged on as when you set the alarm);
however, you can specify that the message be sent to any VESOFT userset (see
"Usersets" in the SECURITY User Manual for details on usersets) using the
;TO=userset option.  For example, to send the message to all users logged on
with SM capability, you might say something like

   %ALARM 'JSCOUNT("LDEV=20")>0', Someone logged on to the console; &
          TO=CAP=SM

Three shorthand keywords are also provided:

   * ;LOGON (the default) means the same as
     TO=!HPJOBNAME,!HPUSER.!HPACCOUNT,!HPGROUP (i.e.  notify anyone logged on
     exactly the same way as the person who set the alarm).

   * ;TERMINAL means the same as TO=LDEV=!HPLDEVIN (i.e.  notify anyone logged
     on to the terminal the alarm was set from, useful if you frequently log
     off and back on with a different user ID, but at the same terminal).

   * ;SESSION means the same as TO=#!HPJOBTYPE!HPJOBNUM (i.e.  notify the
     particular session that set the alarm, not all users that logged on the
     same as the user who set the alarm.  This is useful if you log on with a
     user ID that is the same as other users, but want to limit who sees the
     alarm).

If the message (or the boolean expression) contains embedded commas,
semicolons, or quote characters, enclose the entire message (or boolean
expression) in quotes.


NOHP_507
NOHP
Normally the message is sent using the equivalent of our %WARNF command
(documented in this manual), which writes the message over the function key
labels on HP terminals.  If you know that the terminal to which the message
will be sent is NOT an HP terminal (or emulator), you might want to use the
;NOHP option so that we won't send the escape sequence to write over the
function keys.


MPEXALARMPREFIX_508
MPEXALARMPREFIX
Unlike the :TELL (or %TELL) command, %ALARM messages do not include any
information about who set the %ALARM.  To avoid having to manually include your
name (or session number) in every %ALARM message you set, MPEX will prefix the
message with the contents of the variable MPEXALARMPREFIX (if you %SETVAR it).
For example, to prefix all %ALARM messages with "From Scott: ", you would do a

   %SETVAR MPEXALARMPREFIX "From Scott: "

before you do any %ALARMs.  In fact, you may want to include this %SETVAR in
your MPEXMGR file (see "Specifying Commands To Be Executed Each Time MPEX Is
Entered" in the Running MPEX section of this manual).

REPETITIVE ALARMS


REPETITIVE_ALARMS_509
REPETITIVE ALARMS

The %ALARM task accepts the same repetitive keywords as STREAMX for scheduling
repeating alarms.  The ;REPEAT= keyword lets you use the values DAILY for every
day of the week, WEEKDAY for every "work" day (excludes Saturday and Sunday), a
specific day of the week, or a list of days.  For specific days, you need to
supply at least the first three letters of each day you want the alarm to be
sounded.

Ordinarily, when you use the ;REPEAT= keyword, you would also use ;AT= to
specify a particular time each day that the alarm should be triggered.  If you
use ;REPEAT= without ;AT=, the scheduled time for the alarm will be the time of
day that you issued the command.  So if you type:

     %ALARM "","Quitting Time!";REPEAT=WEEKDAY

at 4:00 in the afternoon, then this alarm will be executed at 4:00 each
weekday.

The keywords ;WHEN and ;WHENEVER are used to specify a condition that when true
will signal an alarm.  ;WHEN is used to set up a single event alarm -- when the
condition becomes TRUE, the alarm is triggered and deleted from the scheduler.
;WHENEVER is used to set up a multiple event alarm -- as long as the condition
is TRUE, the alarm will be sounded.

SECURITY CONSIDERATIONS

For security reasons, non-SM users are not allowed to use certain functions in
the boolean expression when they set an alarm (some functions are not even
allowed for SM users, because their use might hang the ALARM background
process, but most of these wouldn't be very useful in an alarm anyway).  The
restricted functions include:

   *  the MPE(...), PAUSE(...), and PRINTOPREPLY(...) functions;

   *  all VEFaccess and VEDBaccess functions (like VEFOPEN, VEDBOPEN, etc.);

   *  the LOCKWORD, ACCESSIBLEBY, FSEARCHEXP, and FSEARCHSTRING file attributes
      (for example, using the VEFINFO function);

   *  all of the terminal input functions (INPUT, READSTRING, etc.)

   *  all of the variable-setting functions (SETVAR, SVARSET, etc.)

   *  all of the object info functions (VEUSERINFO, VEACCTINFO, etc.)

   *  all SECURITY-related functions (SECURITYLOG, VEPROFILEINFO, etc.)

PERFORMANCE CONSIDERATIONS


VESOFTALARMPAUSE_510
VESOFTALARMPAUSE
By default, the ALARM task wakes up and checks each alarm once each minute.
This can be changed by setting the variable VESOFTALARMPAUSE in the BACKG
initialization file.  For example, adding the line:

   SETVAR VESOFTALARMPAUSE 15

to the file BACKGINI.DATA will cause the ALARM task to wake up every 15
seconds, or 4 times each minute.


CHECKEVERY__511
CHECKEVERY=
Each time the ALARM background task wakes up, every alarm that has been set
will be tested.  If you set an %ALARM based on an expression that uses a lot of
system resources (CPU, disc I/Os, etc.) to evaluate, you may want to check that
particular alarm less frequently.  When you enter an %ALARM command, simply
append the ;CHECKEVERY= keyword to tell the ALARM background task how many
intervals to skip before checking the particular expression you are entering.
For example,

   %ALARM "JSCOUNT('COMPILE,@.@&EXEC')=0", Compiles are done!; &
      CHECKEVERY=10

This means "notify me when there are no more jobs executing that logged on with
a jobname of COMPILE, (but only check every 10th time the task wakes up").

VIEWING PENDING ALARMS (%SHOWALARM)


_SHOWALARM_512
%SHOWALARM
To see what alarms you currently have set, type %SHOWALARM.  This will show you
all of the alarms set by anyone logged on using the same session, user, and
account name you are currently logged on to.  For each alarm, you will see:

   * an alarm number (you need this for the %DELETEALARM command, documented
     below);

   * the time the alarm is set to "go off", or the expression which this alarm
     is set to test;

   * the message this alarm will send when it "goes off".

If you say %SHOWALARM;ALL, you will also see:

   * who set the alarm;

   * who the message is to be sent to;

   * any other special options set (;CHECKEVERY=, or ;NOHP).

If you have SM capability, you can use the ;FROM= option to see alarms set by
other users.  For example,

   %SHOWALARM;FROM=@.@;ALL

will show you all alarms set by any users, and all parameters of those alarms.

DELETING PENDING ALARMS (%DELETEALARM)


_DELETEALARM_513
%DELETEALARM
To delete pending alarms, first do a %SHOWALARM (documented above) to find out
the alarm number.  Then simply type %DELETEALARM and the number of the alarm
you wish to delete; for example, to delete alarm #5:

   %DELETEALARM 5

Unless you have SM capability, you can only delete alarms that were set while
logged on with the same session, user, and account name you are currently
logged on with (these are the only alarms that %SHOWALARM shows you).


_ALIAS_MPEX_command__514
%ALIAS MPEX command

Syntax:   %ALIAS [aliasname command]

          %UNALIAS aliasname

Examples: %ALIAS WT WARNF TOM,@.@;From Ron:
          %WT This is a test of an alias...

          %ALIAS SS SHOWJOB JOB=@S
          %SS
          %UNALIAS SS

          %ALIAS

The %ALIAS commands allows you to create your own commands, sort of like UDCs
or command files.  So, why have a separate command when you could just use UDCs
or command files?

   * UDCs are hard to modify.  You must get everyone who is using them to log
     off, then do a :SETCATALOG.

   * Command files, while easier to change, require a separate file for each
     new command (on MPE/iX, the smallest amount of space a file can take is 16
     sectors, or 4096 bytes!)

   * Both UDCs and command files require you to create a file, which means
     stopping what you're doing long enough to run some editor.

Aliases are created by simply typing "%ALIAS", an aliasname (which can be
anything that an MPEX variable name can be), and the command to be executed
when you enter that alias.  When you log off, all of your alias are
automatically deleted.  This makes it very convenient for you to create a
simple, immediate shortcut for some complex sequence that you need to do
repetitively (perhaps only for one day).

For example, suppose you're testing some program, and you have to run it with a
long INFO= string to test it, but not when it is put into production
(presumably, you already have a UDC or command file that does this).  You could
say something like:

   %ALIAS TESTIT RUN MYPROG;INFO="TESTDATA1 TESTDATA2"

Now, all you have to do is say

   %TESTIT

But, what if you need to run it with different parms? You could create several
aliases, but a better solution would be

   %ALIAS TESTIT RUN MYPROG;INFO="TESTDATA1 TESTDATA2";PARM=

Then you can say

   %TESTIT 20           (* to run with PARM=20 *)
   %TESTIT 32           (* to run with PARM=32 *)

As you can see, everything you type after the alias name is appended to the
command that corresponds to that alias.

To see a list of your current aliases, simply type

   %ALIAS

without any parameters.


_UNALIAS_515
%UNALIAS
To remove an alias, type

   %UNALIAS aliasname


_ALLOCATE_MPEX_command__516
%ALLOCATE MPEX command

Syntax:   %ALLOCATE PROCEDURE,  procname

          %ALLOCATE [PROGRAM,]  fileset
                    [;LIB=  G | P | S ]

Examples: %ALLOCATE MY.OWN.PROGRAM;LIB=G
          %ALLOCATE @.PUB.VESOFT-MAIN.PUB.VESOFT;LIB=P
          %ALLOCATE PROCEDURE, VECMMND

MPEX has enhanced the normal MPE :ALLOCATE command to allow the use of the
traditional ;LIB=G or ;LIB=P parameter (;LIB=S is also supported but has no
effect as it is the default).  MPE does not allow specifying ;LIB=G or ;LIB=P
on the allocate command.

As with many other MPEX commands, MPEX allows you to specify a fileset instead
of a single file name.  Note that the file attribute "ISCMPROG" is quite useful
here in determining which files even NEED to be allocated.  For example, when
installing our software, MPEX %HOOKs several programs and places a copy in the
VESOFT account.  To %ALLOCATE all of these programs using ;LIB=P, so that the
HOOK procedure is loaded, type the following command:

      %ALLOCATE @.PUB.VESOFT(ISCMPROG);LIB=P


_ALTFILE_517
%ALTFILE

Syntax:   %ALTFILE fileset
                            General Characteristics
          [;CAP= [+|-] progcapability [ ,...  ]]           (CHG)
          [;CODE= filecode]
          [;KEEPAMDATES]
          [;LOCKWORD= lockword]
          [;MAXDATA= progmaxdata]
          [;STACK= progstacksize]

                           File Ownership and Access
          [;CREATOR= username]
          [;CREATOR= username [.accountname]]              (NEW - POSIX)
            [;NOCHECK]                                     (NEW - POSIX)
          [;DELACD]                                        (NEW)
          [;GROUPID= groupid]                              (NEW - POSIX)
          [;LOCAL[GROUPID]]                                (NEW - POSIX)

                              Physical Structure
          [;BINARY|ASCII]                                  (NEW)
          [;BLKFACT=  blockingfactor|BEST ]
          [;DEV=  devicenumber|deviceclass ]
          [;EXTENTS= maxextents]
          [;FIXED|VARIABLE|UNDEF|BYTE]                     (NEW)
          [;FLIMIT= flimitspecifier]
          [;INITEXTENTS= initialextents]
          [;KEEPTRAIL]                                     (NEW)
          [;REC= newrecordlength]                          (NEW)
          [;SQUEEZE]
          [;XLTRIM]

The %ALTFILE command can change many of a file's attributes.  It can:

  -  Save disc space (XLTRIM, FLIMIT, SQUEEZE, BLKFACT);

  -  Better manage the disc space you have by moving files from drive to drive
     (DEVICE);

  -  Make room in files (MPE or KSAM!) that are out of space (FLIMIT);

  -  Speed up file access (BLKFACT);

  -  Let you transfer ownership of files from one user to another (CREATOR=),
     including ACCOUNT (GROUPID=) information on MPE/iX systems that support
     POSIX as well as removing ACDs (DELACD) that would override normal MPE
     security;

  -  Change the attributes of improperly :PREPed program files, preventing
     run-time capability errors and stack overflows (CAP, MAXDATA, and STACK);

  -  Alter the file codes and lockwords of files or filesets (CODE, LOCKWORD).

  -  Change file's internal structure (FIXED, VARIABLE, UNDEF, BYTE)

  -  Change the file from ASCII to BINARY (or the other way around, if you
     prefer)

  -  Change the length of each record, optionally keeping trailing SPACES for
     ASCII files, if desired.  (REC= and ;KEEPTRAIL)

All of these options are described in detail below.  Note that you can combine
any of the above options on one command, as well as use these parameters on a
%COPY command (see the %COPY command for more details & examples).  e.g.

   %ALTFILE @.DATA; BLKFACT=BEST; EXTENTS=32; FLIMIT=EOF*1.5

or

   %COPY MYPROG, YOURPROG; CAP=+PH,DS; MAXDATA=30000

POSIX NOTE: %ALTFILE SECURITY CONSIDERATIONS


POSIX_NOTE___ALTFILE_SECURITY_CONSIDERATIONS_518
POSIX NOTE: %ALTFILE SECURITY CONSIDERATIONS

Ordinarily, an account manager can use the %ALTFILE command against any file
within any group of his own account.  On systems supporting POSIX, files have
an attribute called the FILEGROUP (which is the ACCOUNT of the OWNER of the
file).  Since a system manager can %RENAME a file to another account, it is
possible to have a file that an account manager cannot alter because the file
belongs to a FILEGROUP that is different from the account manager's FILEGROUP.

CHANGING FILES' BLOCKING FACTORS (;BLKFACT=)


BLKFACT_519
BLKFACT


Disc_space_520
Disc space

Syntax:   %ALTFILE fileset;BLKFACT=expression|BEST

Examples: %ALTFILE @.DATA(ISASCII); BLKFACT=BEST
          %ALTFILE MYFILE; BLKFACT=128

This keyword of the %ALTFILE command lets you change a file's blocking factor
(or the blocking factors of a set of files).  You can set the new blocking
factor to a given number or let MPEX choose the best possible value (in terms
of disc space) by specifying ;BLKFACT=BEST.


MPE_V_and_MPE_iX_differences___ALTFILE__BLKFACT__521
MPE/V and MPE/iX differences: %ALTFILE ;BLKFACT=
   NOTE: %ALTFILE ;BLKFACT= works on all systems, including MPE/iX; however,
         since blocks are handled quite a bit differently under MPE/iX, this
         discussion and the advantages described in it might not apply to
         MPE/iX machines.  If you're using MPE/iX, you might want to skip the
         %ALTFILE ;BLKFACT discussion altogether.

SAVING DISC SPACE

Bad blocking factors can waste disc space.  For example, typing

   :BUILD RPTLIST;REC=-133,,,ASCII;CCTL

will make MPE assign a default blocking factor of 1, which will waste 47.5% of
the disc space used by the file! MPE's default blocking factors, which are
optimized to save memory (no longer a scarce resource) can often result in very
bad disc space usage.

Typing a command such as

   %ALTFILE @.DATA(ISASCII); BLKFACT=BEST

will set the blocking factors of ASCII (plain vanilla) files in the DATA group
to the BEST blocking factor -- the best in terms of disc space usage.

If several different blocking factors would result in the same file size, MPEX
chooses the HIGHEST one to optimize access speed.

The blocking factor can be BEST, an integer constant, or an EXPRESSION
calculated from various file parameters (the same ones available in selection
criteria).  For instance, you might want to set a file's blocking factor to
8192 divided by the record size (in bytes):

   %ALTFILE @.DATA(ISASCII); BLKFACT=8192/RECSIZE

(This, of course, will set the blocking factor to the highest value such that
the resultant block size is <= 8192 bytes.) If we also want to limit the
blocking factor to at most 100, we could say:

   %ALTFILE @.DATA(ISASCII); BLKFACT=MIN(8192/RECSIZE,100)

This ability to specify expressions as %ALTFILE parameters is available on the
;BLKFACT= and ;FLIMIT= keywords; it isn't (currently) available on any of the
others, primarily because we haven't found any case in which we think it'll be
useful.  If you can think of one, let us know.

SPEEDING UP FILE ACCESS

In normal buffered file access (the default access mode), the file system does
disc I/Os in units of one block -- the blocking factor is the number of records
in each block.

If a 30,000-record file which has blocking factor 3 is read sequentially, the
file system will have to issue 10,000 disc I/Os.  If the file has a blocking
factor of 100, it could be read in only 300 disc I/Os; although each 100-record
I/O would be somewhat slower than each 3-record I/O, you could still realize a
10-fold performance improvement.

Therefore, it can be quite desirable to increase the blocking factors of some
of your MPE or KSAM files -- especially ones that are accessed sequentially.
For instance, saying

   %ALTFILE DATAFILE; BLKFACT=100

will increase DATAFILE's blocking factor to 100; saying

   %ALTFILE @UDC@; BLKFACT=EOF

will set the blocking factor of all the files that have "UDC" in their file
names to be equal to their current EOF, thus making it possible (on MPE/V) to
read the entire file in one I/O (this only works if the EOF is 255 or less).
It's often a good idea to increase the blocking factor of your UDC files
because they must be read in their entirety every time a user logs on --
increasing their blocking factors can thus greatly speed up logon time.  (Of
course, the UDC files must be un-:SETCATALOGed before reblocking and
re-:SETCATALOGed afterwards.)

Note that you pay for this speed by higher memory usage (as a rule, the system
keeps 2 blocks of memory allocated for every accessor of a disc file -- if your
file has blocking factor 60 and record size 40 words, each of the users of the
file will have 4800 extra words of memory allocated for him).  If you find this
a problem (and most people don't), you can easily lower blocking factors.

WARNING

Like most %ALTFILE options, %ALTFILE ;BLKFACT=BEST doesn't change the data in
your file -- it only changes the format in which the data is kept on disc.
Most of your programs shouldn't care what a file's blocking factor is; however,
a few programs (especially system utilities) do care, and sometimes make
assumptions about a file's blocking factor.

A good example of this is the MPE :SEGMENTER subsystem -- it assumes that all
USL, RL, and SL files have blocking factor 1.  If you change a USL file's
blocking factor, :SEGMENTER won't be able to access the file, not because the
blocking factor change somehow "ruined" the data in the file, but because
:SEGMENTER's assumptions are no longer valid.

Because of this, MPEX doesn't let you change the blocking factor of files whose
file codes are 1024 or greater -- these file codes are generally reserved for
MPE or HP subsystems, which usually make assumptions about the blocking factors
of these files.  This rule prevents you from accidentally rendering some of
your USL files, program files, etc.  unusable.

It is still possible, though, that one of your own programs (or a program
supplied by a third-party vendor) can't handle files whose blocking factors
have been changed.  Naturally, MPEX doesn't know this, and will happily reblock
such a file if you tell it to (remember, "a computer does what you tell it to
do, not what you want it to do").

If this happens to you -- if you change a file's blocking factor (or its file
limit) and your program doesn't like this -- don't panic! Just use %ALTFILE to
change the blocking factor back to whatever it was before.

Similarly, before doing a fileset %ALTFILE ;BLKFACT= check to see if there are
any special files in the fileset -- if there are, try altering one of them
first and seeing if the program that normally accesses it can still do so.  If
you find that the program complains, you can easily exclude that file (and
others like it) by saying something like

   %ALTFILE @.@(CODE<>"557" and CODE<>"558"); BLKFACT=BEST

(One more note: Actually, %ALTFILE ;BLKFACT=BEST also forbids changes of files
with file code 111 [QEDIT files] but allows changes of files with file code
1052 [EDTCT files].)

CHANGING PROGRAM FILES' CAPABILITIES (;CAP=)


CAP_522
CAP


Privileged_mode__adding_removing_PM_from_programs_523
Privileged mode: adding/removing PM from programs


MR_capability__adding_removing_MR_from_programs_524
MR capability: adding/removing MR from programs


DS_capability__adding_removing_DS_from_programs_525
DS capability: adding/removing DS from programs


PH_capability__adding_removing_PH_from_programs_526
PH capability: adding/removing PH from programs


IA_capability__adding_removing_IA_from_programs_527
IA capability: adding/removing IA from programs


BA_capability__adding_removing_BA_from_programs_528
BA capability: adding/removing BA from programs

Syntax:   %ALTFILE fileset;CAP=[+|-][IA,BA,PH,PM,MR,DS]

Examples: %ALTFILE AP010P; CAP=+PH,DS
          %ALTFILE @.UTIL.SYS(ISPROG); CAP=-PM,PH,MR,+DS

In order to do certain things -- create son processes, acquire extra data
segments, lock multiple files/databases, or use privileged mode -- a program
must be :PREPed (or, for MPE/iX native mode programs, :LINKed) with the
appropriate capabilities.

What if you omit the right capability? With MPEX you don't need to re-:PREP the
program (or recompile it if you've lost the USL); you can just give it the
capabilities that it should have.  For instance, saying:

   %ALTFILE AP010P; CAP=+PH,DS

will add to the program file AP010P the capabilities PH and DS (without
removing any of the capabilities it already possesses).

Similarly, you can use %ALTFILE to remove capabilities from a program.  For
example,

   %ALTFILE @.UTIL.SYS(ISPROG and PROG.PMCAP); CAP=-PM

will remove PM capability from all the UTIL.SYS programs that have PM.

Specifying all capabilities without a + or - (e.g.  %ALTFILE XFILE; CAP=PH,DS)
is the same as specifying them with a +; it adds the capabilities while
retaining any other capabilities the program might have.  However, specifying
;CAP=PH,-MR,DS is equivalent to ;CAP=+PH,-MR,-DS.  Similarly, specifying
;CAP=-BA,PM,PH,+MR,DS would be treated as ;CAP=-BA,-PM,-PH,+MR,+DS.  In other
words, unsigned capabilities retain the same sign as the previous capability
listed.

As we implied above, %ALTFILE ;CAP= also works on MPE/iX native program files.

RELATED MPEX FEATURES

In addition to being able to alter a program file's capabilities, MPEX lets you
do a couple of other things that MPE doesn't let you do easily (or at all):

   * List a program file's capabilities:

     %LISTF MYPROG.DEV,5
     FILENAME  MAXDATA STACK DLSIZE DBSIZE #SEGS  CAPABILITIES

     MYPROG      30000  2048      0   4604    28  BA IA PM DS PH

     As you see, a number of important file parameters, including the MAXDATA,
     the capabilities, the program's global storage size (in this case, 4604)
     and the program's number of segments (28) are shown.

     Another way to see this (and much more) information about program files is
     with the %PROGINFO command (described in this manual).

   * Find all programs with (or without) a specific capability:

   %LISTF @.@.@ -@.@.VESOFT&
            - @.PUB.SYS(ISPROG and PROG.PMCAP),5

   %LISTF / - /VESOFT/&
            - @.PUB.SYS(ISPROG and PROG.PMCAP),5  (POSIX)

     will find for you all the programs in the system (except for those in the
     VESOFT account or in PUB.SYS) that are allowed to use PM capability.

These two options can often work hand in hand with the %ALTFILE ;CAP= facility.

CHANGING FILES' CODES (;CODE=)


CODE_529
CODE

Syntax:   %ALTFILE fileset;CODE=filecode

Examples: %ALTFILE MYDB; CODE=400
          %ALTFILE MYDB01; CODE=401

In addition to all the other things, MPEX also lets you change a file's file
code.

Why would you want to do this? There are several possible reasons:

   * Some (though by no means all) communication programs (especially
     PC-to-HP3000 transfer utilities) always build HP3000 files with code 0 --
     if you download a file to a PC and then upload it back, you'll find that
     you've lost the filecode.  %ALTFILE ;CODE= can put it back.

   * Since the file system normally doesn't care much about a file's filecode
     -- a normal program can read a file with one filecode just as well as with
     another -- the filecode can be a convenient way of "marking" files.  Thus,
     you can set some of your data files to a particular filecode so they look
     more distinct on :LISTFs and so they can be selected with MPEX's selection
     conditions.

     An interesting idea is for marking "ephemeral" files -- files that you
     know you'll only be using for a few days and want to automatically purge,
     say, at the end of the week.  Whenever you build such a file you might
     %:ALTFILE ;CODE= it -- then, even if you forget about it, you can easily
     find it when you want to clean your discs.

     If you want to get really fancy, you might have a convention to set the
     filecode to 1 if you want to keep the file for 1 day, to 2 if you want to
     keep it for 2 days, etc.  Then, you can periodically say:

        %PURGE @.@(BETWEEN(INTCODE,1,14) and ACCDATE<TODAY-INTCODE)

      This will purge all the files whose code is between 1 and 14 and which
      haven't been accessed in that many days!

   * You may also want to change a file's filecode if the code is currently
     negative (i.e.  PRIV, quite likely an IMAGE file).  If you want to
     manipulate IMAGE files using a program that normally can't handle them
     (e.g.  DSCOPY or DISKED5), you might want to alter the file's filecode to
     a positive value, do whatever you need to do, and then alter the filecode
     back.

     Needless to say, you can get into a lot of trouble this way.  Naturally,
     MPEX only allows a database's creator, its account manager, or the system
     manager (all three of whom can do anything to the database anyway) to do
     this operation; we also encourage people to be very careful with what they
     do with the internal structures of their precious databases.

     However, under some circumstances (with somebody who knows what he's
     doing), this can be a rather useful feature.

Note, however, that changing a filecode to some value doesn't magically make
that type of file.  For instance, if you change a source file's filecode to
PROG, the file won't become a valid program file; the :RUN command will just
give you some nasty error message when you try running it.  If you change the
code to some other system-defined value (e.g.  USL, SL, etc.), whatever program
accesses the file will probably complain.  Use this option carefully.

CHANGING FILES' OWNERSHIP (;CREATOR= & ;GROUPID=)


CREATOR_530
CREATOR


LOCALGROUPID_531
LOCALGROUPID


NOCHECK_532
NOCHECK

Syntax:   %ALTFILE fileset;CREATOR=username
          %ALTFILE fileset;CREATOR=username;NOCHECK
          %ALTFILE fileset;CREATOR=username.acctname       (POSIX)

          %ALTFILE fileset;GROUPID=groupid                 (POSIX)
          %ALTFILE fileset;GROUPID=groupid;NOCHECK         (POSIX)
          %ALTFILE fileset;LOCALGROUPID                    (POSIX)

          %ALTFILE fileset;creator=username;DELACD         (NEW)
          %ALTFILE fileset;GROUPID=groupid;DELACD          (NEW)

 Examples: %ALTFILE @.@(CREATOR="TOM"); CREATOR=MANAGER.SYS
           %ALTFILE @.@(CREATOR<>"DBA" and ISPRIV); CREATOR=DBA

           %ALTFILE @.@.SYS;GROUPID=SYS
           %ALTFILE @.@.@;LOCALGROUPID
           %ALTFILE @.SOURCE;CREATOR=NOBODY.ATALL;NOCHECK

A file's creator ID is often very important:

   * MPE's :RENAME, :RELEASE, :SECURE, and :ALTSEC commands can only be
     performed by a file's creator (although MPEX's %RENAME, %RELEASE, %SECURE,
     and %ALTSEC don't have this restriction).

   * As a rule, many database utilities can only be run by a file's creator
     (unless you use maintenance words).

   * An ordinary :RESTORE (without ;CREATE) requires the file's creator ID to
     exist in the system.

Say that one of your programmers left your company; naturally, the first thing
you did is :PURGEUSERd his user ID.  Now, all his files are "orphans" -- they
can't be :RENAMEd, :RELEASEd, :SECUREd, or :ALTSECed; his databases can't be
DBUTILd; and unless you're careful enough to put a ;CREATE on all your
:RESTOREs (e.g.  after your next RELOAD), they won't be restored.

What you really need to be able to do is to "re-assign" all of these "orphans"
to another user.  For instance, you might say:

   %ALTFILE @.@(CREATOR="TOM"); CREATOR=MANAGER
   %ALTFILE @.@(CREATOR="TOM"); CREATOR=MANAGER.SYS;GROUPID=SYS  (POSIX)

This will find all the files in your account that have creator ID TOM and
change their creator ID to be MANAGER (or MANAGER.SYS).  Similarly,

   %ALTFILE @.@(CREATOR<>"DBA" and ISPRIV); CREATOR=DBA

will change all your databases (which don't already have a creator id of DBA)
to be "owned by" DBA.

RELATED POSIX FEATURES


_ALTFILE__CREATOR___GROUPID_533
%ALTFILE ;CREATOR & GROUPID

Just changing the name of the creator, however, doesn't completely change the
"ownership" of a file on a POSIX system.  On these systems, a file is "owned"
by the CREATOR and the account manager of the GROUP in which the file resides.
Note that this is NOT the MPE group, but rather the POSIX "GROUP ID", (which
has its roots in the UNIX operating system) and is, in reality, an MPE ACCOUNT
name.


DELACD_534
DELACD
When a file is RENAMEd from one account to another (using either MPEX or MPE
itself), the CREATOR and GROUPID don't change, so the CREATOR and account
manager of the account where the file was originally built retain "ownership"
of the file.  In order to enforce this, MPE may place an Access Control
Definition (ACD) on a file that has been renamed.

In order to change the ownership of all files on your system to the account
where each file now resides, use the ;LOCALGROUPID (which can be abbreviated to
;LOCAL) and ;CREATOR keywords as shown here:

   %ALTFILE @.@.@;LOCALGROUPID;CREATOR=MANAGER;DELACD

(This presumes that all of your account managers have a user ID of MANAGER;
however, many sites use MGR as the account manager.) If you want to set the
ownership of a set of files to a particular GROUP ID (for instance, to secure
the source of all of your job streams in a particular account), you can use the
following:

   %ALTFILE @.JOBS.PROD;GROUPID=SYS;CREATOR=MANAGER.SYS

This would effectively make the system manager the "owner" of all of your job
streams in the PROD account.

NOTE: ;GROUPID= and ;LOCALGROUPID are mutually exclusive -- you can specify one
or the other but not both in the same command.

As the examples above show, the ;CREATOR= keyword allows you to specify the
ACCOUNT as well.  If no account is specified, MPEX will assign the account name
where the file resides as the account name of the creator.  In addition to
specifying the MPE user ID and account, you can use an asterisk to indicate
yourself or an equals sign to indicate that the field should retain whatever
value it currently contains.

By "yourself", we mean the MPE user & account information for your current
logon.  For instance, if you are logged on as MANAGER.ACCTING and type:

   %ALTFILE @.DATA;CREATOR=*.*

then it would be equivalent to entering ;CREATOR=MANAGER.ACCTING.

The "=" character retains whatever value is currently in the field, so if a
file was "created" by CLERK.PAYROLL, then this command:

   %ALTFILE @.DATA;CREATOR=MGR.=

would be the same as saying ;CREATOR=MGR.PAYROLL.

One final note: to maintain compatibility with MPE, MPEX generally will not let
you change a file to be "owned" by a non-existent user.  This restriction can
be overridden in MPEX by supplying the ;NOCHECK keyword on the %ALTFILE
command.

RELATED MPEX FEATURES

We've already seen how the CREATOR= selection condition can work very well with
the %ALTFILE ;CREATOR= command.  Another relevant feature is:

%LISTF MYFILE.PUB.SYS,3
FILENAME  CREATOR  CRE-DATE  MOD-DATE  MOD-TIME  ACC-DATE  RST-DATE

MYFILE    MANAGER  11 AUG 91 24 DEC 91 10:52 AM 05 FEB 91 30 DEC 91

As you see, %LISTF mode 3 shows you creator IDs, times, and dates.


Finding_files_with_non_existent_creators__535
Finding files with non-existent creators
Another interesting use of MPEX selection conditions in %ALTFILE ;CREATOR= is
the following:

   %ALTFILE @.@(NOT USEREXISTS(CREATOR+"."+ACCOUNT)); CREATOR=MGR

Wow! What does all this mean? Well, the selection condition here is:

   NOT USEREXISTS(CREATOR+"."+ACCOUNT)

We're executing the MPEX built-in function USEREXISTS(..), and passing to it
the file's creator, concatenated with a "." and the file's account.  The
USEREXISTS function (which you can look up in Appendix to this manual) returns
TRUE if a particular MPE user.account exists.  We said "NOT USEREXISTS..."
because we want to select those files whose creator does NOT exist.  Therefore,
MPEX will change to "MGR" the creator of all files (in your logon account)
whose current creator doesn't exist in the file's account.

Similarly, if you have SM capability, you could say

   %LISTF @.@.@(NOT USEREXISTS(CREATOR+"."+ACCOUNT)),3

and find all the files in the system whose creators don't exist.

MOVING FILES FROM DISC TO DISC (;DEV=)


DEV_536
DEV


IMAGE_databases__moving_from_disc_to_disc_537
IMAGE databases: moving from disc to disc

Syntax:   %ALTFILE fileset;DEV=devicenumber|deviceclass

Examples: %ALTFILE CUST?#.DB(DBSETTYPE="D"); DEV=2
          %ALTFILE CUST?#.DB(DBSETTYPE<>"D"); DEV=3
          %ALTFILE @.@(ONDEVICE(1)); DEV=APPDISC

Which disc drives a file resides on can have a substantial impact on system
performance.  One popular theory holds that having frequently-accessed files on
the same disc drive can increase contention for that drive and therefore slow
down access to it.  Therefore, many people like to:

   * Keep frequently-accessed IMAGE master and detail files on different
     drives;

   * Keep KSAM data files on different drives than their key files;

   * Minimize the amount of non-system files that reside on device 1 (since it
     is already heavily used for system access, directory access, and sometimes
     for virtual memory access).

MPEX is the most convenient tool for doing this sort of thing.

For example, saying

   %ALTFILE CUST?#.DB(DBSETTYPE="D"); DEV=2
   %ALTFILE CUST?#.DB(DBSETTYPE<>"D"); DEV=3

will move all the detail datasets of the CUST database (the selection condition
DBSETTYPE="D" will select only the detail datasets) to disc drive #2, and all
the non-detail (manual or automatic) datasets to disc drive #3.  Similarly,

   %ALTFILE @.@(ONDEVICE(1)); DEV=APPDISC

will move all the files in your account that have at least one extent on device
#1 to the device class called APPDISC (which might be configured to include all
disc drives except for device 1).

WHAT YOU SHOULD KNOW ABOUT EXTENTS

Before moving a lot of files, you must be aware of some little-known facts
about the way disc files are built.

By default, a disc file is built on device class DISC, which is (usually)
configured to include all the disc drives in the system.  This means that each
of a file's extents could conceivably be on a different disc drive.  For
instance, if you use MPEX's %LISTF ,4 to look at a file's extent map, you might
see the following:

-----FILE------ EXTENTS -BLKFACT- -----SECTORS-----  DEVICE      LABEL
NAME      CODE  NUM MAX  NOW BEST USED NOW  SAVABLE  CLASS       LDEV

LOG0679          16  16    1          8192           DISC        2
   Dev/Sector:    2/%00000241110   3/%00000105237   1/%00000544165
   Dev/Sector:    1/%00000537652   3/%00000523744   4/%00000534046
   Dev/Sector:    3/%00000531514   2/%00000544520   4/%00000526374
   Dev/Sector:    2/%00000540024   1/%00000540652   1/%00000535347
   Dev/Sector:    1/%00001120104   2/%00001310054   4/%00000763606
   Dev/Sector:    1/%00001137722

As you see, this file has 6 extents on device 1, 4 extents on device 2, 3
extents on device 3, and 3 extents on device 4.

However, your :STORE listing will show this file as being "on device #2" --
:STORE always shows the device number of the file label! Similarly, LISTDIR5's
>LISTF will show the file as being "on device #2"; even >LISTF ;MAP won't
conveniently show you on which devices the file is actually located (it shows
"volume table indexes", which are not the same as device numbers).  MPE/iX has
a :LISTF ,3 (not the same as MPEX's %LISTF ,3!) that shows the "DISC DEV #",
but this is actually the disc that the file label is on; the beginning of the
file itself may be on a completely different disc!

Therefore, when you're figuring out which files should be moved, be sure that
you have all the data! Do a %LISTF ,4 first to see exactly on which disc drive
a file is located -- even if you see a data and key file which :STORE shows as
being on different disc drives, it may be that they're actually mostly on the
same device.

Another relevant feature is the ONDEVICE(devnumber) selection criterion we
mentioned above.  Saying

   %ALTFILE @.DATA(ONDEVICE(1)); DEV=APPDISC

will select (and move) those files that have at least one extent on device 1.
Thus, any files which are even partially on the system disc will be moved.

The criteria that are related to file position are:

   ONDEVICE(devnumber)          TRUE if the file has at least one extent on the
                             given device

   DEVICESECTORS(devnumber)     An integer that indicates how many sectors of
                             the file are actually on that device

   DEVICE                       A string indicating the DEVICE CLASS (e.g.
                             "DISC", "SYSDISC", "MEMBER2", or "2") -- a device
                             class may also be a device number

For instance, some interesting commands might be:

     %ALTFILE @.DATA(DEVICESECTORS(1)>=SECTORS/10); DEV=2

      (affects all files that have at least one tenth of their sectors are on
       device 1; moves them onto device 2)

     %ALTFILE @.DATA(DEVICE="SYSDISC"); DEV=APPDISC

(moves to device class APPDISC all the files that were built on device class
       SYSDISC -- not those files that happen to be on a device in that class,
       but those that were explicitly built to be on that device class)

WHAT YOU SHOULD KNOW ABOUT NON-SYSTEM VOLUMES


_ALTFILE_AND_NON_SYSTEM_VOLUME_SETS_538
%ALTFILE AND NON-SYSTEM VOLUME SETS

When moving files from one device to another, you should also be aware of the
effect non-system volumes have on files.  Note that on an XL system, the SYSTEM
volume set is usually labeled "MPEXL_SYSTEM_VOLUME_SET", while NON-SYSTEM
volume sets are given an arbitrary name when they are created.  On CLASSIC
systems, the SYSTEM volume set does not have any special definition while
NON-SYSTEM volume sets are usually referred to as PRIVATE VOLUMES.

The important thing to understand about volume sets is that the VOLUME SET for
a particular file is not determined by the file itself, but rather the GROUP in
which the file resides determines the VOLUME SET for the file.  While all of
the files in a particular group reside on the same volume set, different groups
within the same account may reside on different volume sets.  For this reason,
when you %RENAME a file from one group to another, you may get an error
indicating that the file cannot be renamed across volume sets.  In this case,
the file must be %COPYd instead.

For example, lets take a system with eight drives, LDEVs 1, 2, 3, & 4 are the
SYSTEM volume set, and LDEVs 5, 6, 7, & 8 are  a NON-SYSTEM volume set.  On
this system, the account DEMO has three groups, PUB, SYSTEM, and PRIVATE.  PUB
and SYSTEM are in the SYSTEM volume set and PRIVATE is on the NON-SYSTEM volume
set.

To move the file SHOW.PRIVATE.DEMO to SHOW.PUB.DEMO, you must use the %COPY
command instead of the %RENAME command since these groups are in different
volume sets.  For the same reason, you cannot %ALTFILE SHOW.PRIVATE.DEMO;DEV=2
but you could %ALTFILE SHOW.PRIVATE.DEMO;DEV=8.  In general, however, you could
%ALTFILE SHOW.PRIVATE.DEMO;DEV=DISC since the device class of DISC may be
applied to devices in different volume sets (and is usually applied to all
physical disc devices when configured).  When you use ;DEV=DISC for a file on a
non-system volume set, the file is placed on any disc within that set, so the
file SHOW.PRIVATE.DEMO would exist on LDEV 5, 6, 7, or 8 after the above
command was executed.


MOVING_GROUPS_TO_A_NON_SYSTEM_VOLUME_SET_539
MOVING GROUPS TO A NON-SYSTEM VOLUME SET
In order to move a group from a SYSTEM volume set to a NON-SYSTEM volume set,
you need to use the :NEWGROUP and :ALTGROUP commands to define the group on the
non-system volume set.  The group must be empty when you do this, so you must
:STORE, and %PURGE the files prior to moving the group, then :RESTORE the files
after the group has been moved.

This works fine for a single group, but could become tedious for a large number
of groups.  Our VEAUDIT product has been enhanced to perform %ALTGROUP commands
against groupsets, so moving groups from a system volume set to a non-system
volume set is relatively easy (see the VEAUDIT manual for details).

CHANGING FILES' MAXIMUM # OF EXTENTS (;EXTENTS=)


EXTENTS_540
EXTENTS


Disc_space_541
Disc space

Syntax:   %ALTFILE fileset;EXTENTS=maxextents

Examples: %ALTFILE MYFILE;EXTENTS=32
          %ALTFILE @.DATA(EOF<FLIMIT and MAXEXTENTS<>32);EXTENTS=32


MPE_V_and_MPE_iX_differences___ALTFILE__EXTENTS__542
MPE/V and MPE/iX differences: %ALTFILE ;EXTENTS=
   NOTE: %ALTFILE ;EXTENTS= works on all systems, including MPE/iX; however,
         since extents are handled quite a bit differently under MPE/iX, this
         discussion and the advantages described in it might not apply to
         MPE/iX machines.  If you're using MPE/iX, you might want to skip the
         %ALTFILE ;EXTENTS= discussion altogether.

A disc file may be built as any number (from 1 to 32) of chunks of contiguous
disc space.  Each such contiguous chunk is called an extent.

The most important thing about extents is that a file is always allocated
extent by extent:

   * If you build an entirely empty file -- one that contains no data -- an
     entire extent of the file will have to be allocated (if the file has file
     limit 100,000 and a maximum of 8 extents, then enough room for 12,500
     records will be allocated even if none of them are actually used);

   * Whenever a file is not full -- its EOF is less than its FLIMIT -- 1/2 of
     an extent is, on the average, wasted.

For instance, in that file with FLIMIT 100,000 and a maximum of 8 extents, on
the average 6,250 records worth of data will be wasted -- allocated but not
used.  For example, in the file

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

   MYFILE          134B  FAC      13215     100000  21    13112  2  8

6,171 sectors of data (almost half!) are wasted -- there are only 13,215
records in it, but since each extent has 12,500 records (100,000 / 8), MPE
allocates enough disc space for 25,000!

What this really means is that:

   * Whenever you expect a file to have EOF < FLIMIT, you should build it with
     a maximum of 32 extents, the largest value allowed by MPE.  (MPE's default
     is 8, which is less efficient than 32.)

     With 32 extents, the average amount of wasted space (1/2 of an extent) and
     the maximum amount of wasted space (1 full extent) will both be minimized.

For instance, if in the above example we say:

   %ALTFILE MYFILE;EXTENTS=32

then our file would look like:

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

   MYFILE          134B  FAC      13215     100000  21     8195  5 32

Simply by increasing the maximum number of extents for the file (which doesn't
decrease the room available in the file at all), we've saved 4,917 sectors, or
37.5% of the file's disc space! There's still some "wasted" space, but it's a
lot less now than it was before.

A good example of the use of MPEX filesets on the %ALTFILE command might be:

   %ALTFILE @.DATA(EOF<FLIMIT and MAXEXTENTS<>32);EXTENTS=32

This finds all the files that are not full (EOF<FLIMIT) and don't already have
a maximum of 32 extents and changes them to have a maximum of 32 extents.

Note that the MAXEXTENTS keyword (which indicates the maximum number of extents
this file could have) shouldn't be confused with NUMEXTENTS (which indicates
the number of extents the file currently has).  MAXEXTENTS corresponds to the
"MX" column on a :LISTF ,2; NUMEXTENTS corresponds to the "#X" column.

Also note that sometimes when you ask for a certain maximum number of extents,
MPE will actually build the file with a smaller maximum number of extents --
for instance, %ALTFILEing a file with EXTENTS=32 might actually make the file
have only 29 extents.

This is a feature of MPE which MPEX can do nothing about (the MPE :BUILD
command often does the same thing); in any case, it shouldn't cause any
problems, since the maximum number of extents only affects the disc space
allocated to a file, not the behavior of programs accessing it.

CHANGING FILES' FLIMITS (;FLIMIT=)


FLIMIT_543
FLIMIT


Disc_space_544
Disc space

Syntax:   %ALTFILE fileset; FLIMIT=flimitspecifier

Examples: %ALTFILE @.DATA(INTCODE<>717); FLIMIT=EOF*1.5
          %ALTFILE MYFILE.DATA; FLIMIT=FLIMIT-10000

SAVING DISC SPACE

Whenever a file's FLIMIT is greater than its EOF, chances are that some disc
space will be wasted.  This wasted space can be minimized by increasing the
number of extents to 32 (see ";EXTENTS=" in the %ALTFILE command); but even
then, most of the time there will be some disc space that is allocated but not
used.

Consider, for a moment, the following file:

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

   MYFILE          134B  FAC      13215     100000  21     8195  5 32

As you see, it occupies 8,195 sectors of disc space; however, only about 6,900
of these (13215*134/256) really contain data -- the rest are unused.

However, it's quite possible that MYFILE will never have 100,000 records; it
might be quite safe to leave just enough additional room for, say, half as many
records as are already in the file.  All we need to do is say:

   %ALTFILE MYFILE; FLIMIT=EOF*1.5

and then the file will look like:

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

   MYFILE          134B  FAC      13215      19822  21     7260 22 32

As you see, we've saved 935 sectors, or 11% of the file's disc space.  Only 319
sectors are now wasted (allocated but not used).  And, chances are that the
room left in the file (50% of its current size) should be plenty for any
further expansion.

WHAT IF A FILE OVERFLOWS?

To save disc space, we can lower file limits.  However, what if your data file
(MPE or KSAM) gets full? You built it with room for 20,000 records, so when you
try to write the 20,001st, MPE doesn't let you.  What can you do?

MPEX's %ALTFILE ;FLIMIT= can easily be used to increase file limits as well as
decrease them.  The

   %ALTFILE MYFILE; FLIMIT=EOF*1.5

construct will decrease MYFILE's FLIMIT if it's currently greater than EOF*1.5;
it will increase the FLIMIT if it's currently less than EOF*1.5.  For instance,
if MYFILE currently looks like

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

   MYFILE          144B  FA       19974      20000  16    11259 32 32

we can see that it's almost full.  If we say:

   %ALTFILE MYFILE; FLIMIT=EOF*1.5

it will now look like:

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

   MYFILE          144B  FA       19974      29961  16    11682 22 32

Of course, we could use any of the other ;FLIMIT= options as well; we could say
one of:

   %ALTFILE MYFILE; FLIMIT=30000
   %ALTFILE MYFILE; FLIMIT=FLIMIT+10000
   %ALTFILE MYFILE; FLIMIT=FLIMIT*1.5

any of which will set the file limit to 30,000.  Usually, the FLIMIT=EOF*xxx
construct is the best since it very reasonably represents what you'd probably
like the new file limit to be.

In fact, you might want to have a nightly job stream that says:

   :JOB MAKEROOM, ...
   :RUN MAIN.PUB.VESOFT
    !ALTFILE @.DATA(EOF>0.8*FLIMIT); FLIMIT=EOF*1.5
    EXIT
   :EOJ

This will find all the files that are more than 80% full (EOF > 0.8*FLIMIT) and
set their file limits to 50% more than their current EOFs.  Alternatively, you
might want to expand your data file before running a program that adds a lot of
data to it, and then contract it after the program's done:

   :JOB MYRPT, ...
   :RUN MAIN.PUB.VESOFT;PARM=1
    ALTFILE X77U.DATA; FLIMIT=EOF*5
    RUN X77P.PUB;LIB=P
    ALTFILE X77U.DATA; FLIMIT=EOF*1.1
    EXIT
   :EOJ

This will set the FLIMIT to 5 times the EOF (EOF*5) before the program is run;
after the program's done, it'll set the FLIMIT to 10% more than the new EOF.
It'll take some extra time (but not too much), but will both optimize your disc
space usage AND make sure that the file doesn't overflow.

WARNING

The %ALTFILE ;FLIMIT= option tells the file system what the maximum number of
records in the file is supposed to be.  Usually, this does exactly what you
want it to do -- saves disc space or makes more room for future expansion.

However, some programs make assumptions about how large a file is supposed to
be.  Say that you have a program that 'knows' that the FLIMIT recorded
somewhere within the file itself (the MPE :SEGMENTER subsystem is like that).
Then, when you ask MPEX to change the file's FLIMIT, MPEX will be very happy to
do exactly what you asked -- change the FLIMIT.  However, the data inside the
file (known only to the program that manages the file) will naturally not be
changed.

This is why MPEX doesn't let you do %ALTFILE ;FLIMIT= of RL, SL, or USL files
-- if you try to increase the file limit, it'll have no effect; if you try to
decrease the file limit, you'll confuse :SEGMENTER and when you next try to add
something to the file, the file might even get corrupted.

Even if MPEX let you %ALTFILE ;FLIMIT= of RLs, SLs, and USLs, this wouldn't be
a "bug" -- MPEX would be doing exactly what you told it to do.  However, since
you would never really want to change an RL's, SL's, or USL's file FLIMIT
(because of the problems with :SEGMENTER), MPEX specially checks for this case.

You might have other files just like this that MPEX can't possibly know about
-- for instance, files manipulated by your own programs or some third-party
vendor products.  Whenever a file contains -- somewhere in its data --
information on its own flimit, MPEX's %ALTFILE ;FLIMIT= could cause problems,
since it'll change the FLIMIT but not the data-resident information.  MPEX will
gladly do what you ask, but the program that later accesses the file won't like
it (although the file's data will be exactly the same as before).

To avoid problems with this, you should do the following:

    * Don't panic -- remember, you could always do another %ALTFILE ;FLIMIT= to
      change the FLIMIT back to what it was before.

    * If you suspect that one of your programs may not like %ALTFILE ;FLIMIT=
      of its data files, try this on one file (rather than doing an %ALTFILE of
      an entire group or account).

    * If you do find that some files shouldn't have %ALTFILE ;FLIMIT= done to
      them, you can easily exclude them from your filesets; for instance, if
      files with code 557 and 558 shouldn't have their FLIMITs changed, you can
      simply say

         %ALTFILE @.DATA(INTCODE<>557 and INTCODE<>558); FLIMIT=EOF*1.5

CHANGING FILES' INITIALLY ALLOCATED EXTENTS (;INITEXTENTS)


INITEXTENTS_545
INITEXTENTS

Syntax:   %ALTFILE fileset;INITEXTENTS=initialextents

Examples: %ALTFILE MYFILE;INITEXTENTS=32
          %ALTFILE @.DATA(NUMEXTENTS<>MAXEXTENTS);INITEXTENTS=MAXEXTENTS

%ALTFILE ;INITEXTENTS= lets you specify the initial number of extents to be
allocated to the new file.  This can be useful in several ways:

  * You may want to pre-allocate space for the whole file so that if there's
    not enough room for it on disc, you'll know now rather than when your
    program tries to allocate a new extent for the file (which might be in the
    middle of your batch processing).  To do this, you might do an %ALTFILE
    ;INITEXTENTS=32, which will allocate the file with the maximum number of
    extents (even if that is less than 32).

  * On MPE/iX, you may want to allocate the file as one contiguous chunk of
    disc space -- this can be done with an %ALTFILE ;EXTENTS=1;INITEXTENTS=1.

  * You might want to do an %ALTFILE preserving whatever extent-allocation
    parameters were specified for the current files -- you can do this by
    specifying ;INITEXTENTS=NUMEXTENTS, which means that the new file is to be
    allocated with an initial number of extents equal to the number of extents
    that are currently allocated.

PREVENTING CHANGES TO FILES' ACCESS/MODIFY DATES (;KEEPAMDATES)


KEEPAMDATES_546
KEEPAMDATES

Syntax:   %ALTFILE fileset;...keywords...;KEEPAMDATES

Example: %ALTFILE @.DATA;XLTRIM;DEV=2;KEEPAMDATES

When you do an %ALTFILE, the file's last access and last modify dates will be
set to today's date.  This is rather typical MPE behavior -- after all, you're
both accessing and changing the file, so the last access and the last modify
dates should be updated.

However, sometimes you do not want these dates to be updated.  In particular,
you might not want to update the last access date because you use it for
archival purposes; you might periodically say something like

   %MPEXSTORE @.@.@-@.@.SYS-@.@.TELESUP(ACCDATE<TODAY-180);*TAPE;PURGE

to clean up your system and save disc space.  If you do this, you'd like to
update the last access date as rarely as possible -- update it only when
somebody actually tries to access the file for something productive.  If you
merely say

   %ALTFILE @.DATA;BLKFACT=BEST

you will have all the DATA group files marked as having been accessed today.

Similarly, if your backups take a long time, you might not want to update the
last modify date when you do something as relatively non-intrusive as, say, an
%ALTFILE @.DATA;DEV= -- the files' contents haven't actually changed, so
there's no good reason to force all the altered files to be backed up.

If you say

   %ALTFILE @.DATA;DEV=2;BLKFACT=BEST;KEEPAMDATES

then MPEX will perform all the alterations without updating the last access and
last modify dates.  If you want this to be the standard behavior of the
%ALTFILE command, you can say


MPEXALTFILEKEEPAMDATES_547
MPEXALTFILEKEEPAMDATES

   :SETJCW MPEXALTFILEKEEPAMDATES=1

-- this tells MPEX that the %ALTFILE command should never update the last
access and last modify dates of files even if ;KEEPAMDATES is not specified.
If you're going to use the SETJCW command, you should probably put it into the
MPEXMGR.PUB.VESOFT file so that it comes into effect for all users in the
system.

Note that for technical reasons, MPEX will always update the last access and
modify dates of a KSAM key file when a KSAM file is %ALTFILEd.  We may remove
this restriction in the future, but for the moment it exists.

CHANGING FILES' LOCKWORDS (;LOCKWORD=)


LOCKWORD_548
LOCKWORD

Syntax:   %ALTFILE fileset;LOCKWORD=[lockword]

Examples: %ALTFILE @.UTIL.SYS(PROG.PMCAP); LOCKWORD=SECRET
          %ALTFILE @.PRIV.TELESUP; LOCKWORD=!!RANDOMNAME

The %ALTFILE ;LOCKWORD= option lets you (you guessed it) alter a file's
lockword (or the lockwords of all the files in a fileset).

POSIX note: Since POSIX files cannot have lockwords, this keyword will not work
            with a POSIX fileset.

The advantages of %ALTFILE ;LOCKWORD= over a :RENAME (the normal way of
altering a file's lockword) are:

   * you can %ALTFILE ;LOCKWORD= a file in another account (if you have SM
     capability);

   * you can %ALTFILE ;LOCKWORD= entire filesets;

   * you can %ALTFILE ;LOCKWORD=!!RANDOMNAME to assign a file (or all files in
     a fileset) a RANDOM lockword.  (This is just a special case of the
     RANDOMNAME function [described in Appendix] which can be used for setting
     random lockwords, random MPE passwords, etc.)

For example, you can say:

   %ALTFILE @.@.CONTRIB(ISPROG and PROG.PMCAP); LOCKWORD=XYZZY

to set a lockword on all the program files in the CONTRIB account that have PM
capability.

To assign a random lockword to each of the files in PRIV.TELESUP, use the
following example:

   %ALTFILE @.PRIV.TELESUP; LOCKWORD=!!RANDOMNAME

By assigning a random lockword to each utility in PRIV.TELESUP, you reduce the
possibility that someone could run one of these programs without authorization.
Even if one of the lockwords is discovered, the rest of the utilities are
protected since they each have a different lockword.  When you need to use one
of these utilities, log on with System Manager (SM) capability and either run
the program from MPEX (where we will automatically supply the lockword), or use
MPE's listf modes -1 or -3 to view the lockword.

We use !! instead of just ! so that each file in the fileset being %ALTFILEd
gets its own lockword -- if we use one !, all the files being %ALTFILEd will
get the same random lockword.  This is because a single ! would be resolved
immediately at the time the %ALTFILE command is parsed, rather than just once
for each file -- see the chapter on MPEX Variables for more information.

SECURITY CONSIDERATIONS

A file's lockword may be altered only by the account manager of the file's
account or by the system manager.  On systems that support POSIX, the
definition of the files account manager is slightly different -- see the POSIX
NOTE: %ALTFILE SECURITY CONSIDERATIONS at the beginning of this section for a
detailed explanation.

RELATED MPEX FEATURES

You can also (if you have SM or AM in your own account) use MPEX selection
criteria to find files by lockword (or the absence of one).  For instance, you
might say:

   %LISTF @.@.@(LOCKWORD<>""),2

to find all the files in the system that have a lockword; or, if there are
several files that you want to have the same lockword (e.g.  some secure data
files that only authorized people can access) and you want to periodically
change all these lockwords, you can say

   %ALTFILE @.@.@(LOCKWORD="OLDLOCK"); LOCKWORD=NEWLOCK

and all the old OLDLOCK lockwords will be automatically changed to NEWLOCK.

CHANGING PROGRAM FILES' MAXDATA VALUE (;MAXDATA=)


MAXDATA_549
MAXDATA

Syntax:   %ALTFILE fileset;MAXDATA=progmaxdata

Examples: %ALTFILE AP010P; MAXDATA=30000
          %ALTFILE @.PUB(ISPROG); MAXDATA=30000

The ;MAXDATA= keyword of the :PREP and :RUN commands indicates how much stack
space a program can use.  If your ;MAXDATA= is too low, you're more likely to
get STACK OVERFLOWs; some of these can be fixed just by running the program
with a higher ;MAXDATA=.

%ALTFILE ;MAXDATA= lets you change a program's MAXDATA value just as if you
re-:PREPed with the new MAXDATA.  This way, you neither have to re-:PREP nor
always remember to specify a ;MAXDATA= on the :RUN command -- just do an

   %ALTFILE AP010P; MAXDATA=30000

(30000 is close to the maximum valid MAXDATA of 31232, but not so close that
you might get into trouble with MPE running out of room in your stack to put
its file system tables.)

RELATED MPEX FEATURES

In addition to letting you change a program file's MAXDATA=, we also let you
easily see the MAXDATA:

   %LISTF MYPROG.DEV,5
   FILENAME  MAXDATA STACK DLSIZE DBSIZE #SEGS  CAPABILITIES

   MYPROG      30000  2048      0   4604    28  BA IA PM DS PH

(As you can see, all the various program parameters are shown.)

Actually, we're so flexible that you can even select based on MAXDATA (%LISTF
@.@.@(PROG.MAXDATA>30000),5).

SETTING FILES' FLIMITs = TO THEIR EOFs (;SQUEEZE)


SQUEEZE_550
SQUEEZE


Disc_space_551
Disc space


FLIMIT__setting_it_to_EOF_552
FLIMIT: setting it to EOF

Syntax:   %ALTFILE fileset;SQUEEZE

Examples: %ALTFILE RPT@.DATA; SQUEEZE
          %ALTFILE @.DATA(MODDATE<TODAY-365); SQUEEZE


MPE_V_and_MPE_iX_differences___ALTFILE__SQUEEZE_553
MPE/V and MPE/iX differences: %ALTFILE ;SQUEEZE
   NOTE: If you're using MPE/iX, you'll probably want to use the ;XLTRIM option
         instead of the ;SQUEEZE option -- it saves as much disc space without
         restricting the further growth of the file.

Whenever a file has a file limit greater than EOF, it's almost certain to waste
some space.  You can recover this space by doing an %ALTFILE ;SQUEEZE, which
sets the file limit to be equal to the EOF.

This command is therefore quite similar to an %ALTFILE ;FLIMIT=EOF; however,
because of features provided by MPE, it can be a lot faster.  For more
information, see the %ALTFILE ;FLIMIT= documentation above.

CHANGING PROGRAM FILES' STACK VALUE (;STACK=)


STACK_554
STACK

Syntax:   %ALTFILE fileset;STACK=progstacksize

Examples: %ALTFILE AP010P; STACK=3000
          %ALTFILE @.PUB(ISPROG); STACK=3000

One of the parameters that you can specify on the ;PREP= command is ;STACK=,
the initial Qi-Z area to be allocated for the process.

This is a very little-known and very little-used feature; if you do use it,
%ALTFILE ;STACK= will help you change it if it was specified incorrectly on
your :PREP command.  In reality, this parameter is mostly included just for
completeness.  The really useful program file modification options are ;CAP=
and ;MAXDATA=.

RELEASING FILES' UNUSED DISC SPACE ON MPE/iX (;XLTRIM)


XLTRIM_555
XLTRIM


Disc_space_556
Disc space

Syntax:   %ALTFILE fileset;XLTRIM

Examples: %ALTFILE RPT@.DATA;XLTRIM
          %ALTFILE @.@.@(SAVABLESECTORS>0);XLTRIM; KEEPAMDATES


MPE_V_and_MPE_iX_differences___ALTFILE__XLTRIM_557
MPE/V and MPE/iX differences: %ALTFILE ;XLTRIM
MPE/iX files -- especially those whose EOFs are less than their FLIMITs --
often use more space than necessary.  This happens because MPE/iX doesn't want
to allocate disc space a record at a time; this would take too long and cause
much disc fragmentation.  MPE/iX allocates space in units of up to 2048
sectors, so it's possible that a 1-record file uses an entire 2048-sector chunk
of (contiguous!) disc space.

The %ALTFILE ;XLTRIM command lets you release all this unused space without
changing the file's file limit.  Thus, you can save disc space without making
the file any less extensible -- when you try to append more data to the file
later, MPE/iX will just allocate another chunk of space.

%ALTFILE ;XLTRIM may increase file fragmentation (for files that you frequently
append new records to) -- instead of being a collection of 2048-sector chunks,
a file that is repeatedly XLTRIMed becomes a larger collection of smaller
chunks.  We don't think that this should be much of a problem, but you might
want to keep it in mind.

Our experience has been that you can save truly dramatic quantities of disc
space this way without making the XLTRIMed files any less extensible (since
their file limits remain unchanged).  You might also want to use the %LISTF
,SAVABLE command to get an idea of just how much disc space can be saved this
way.

CHANGING THE INTERNAL STRUCTURE OF A FILE


FIXED_558
FIXED


VARIABLE_559
VARIABLE


UNDEF_560
UNDEF


BYTE_561
BYTE


ASCII_562
ASCII


BINARY_563
BINARY


REC_564
REC


KEEPTRAIL_565
KEEPTRAIL

Syntax:   %ALTFILE fileset;FIXED
          %ALTFILE fileset;VARIABLE [;KEEPTRAIL]
          %ALTFILE fileset;UNDEF
          %ALTFILE fileset;BYTE

          %ALTFILE fileset;ASCII
          %ALTFILE fileset;BINARY

          %ALTFILE fileset;REC=maxrecordlength ;VARIABLE [;KEEPTRAIL]

 Examples: %ALTFILE RPT@.DATA;ASCII;VARIABLE;REC=80;KEEPTRAIL
           %ALTFILE NEW.UPLOAD;BINARY
           %ALTFILE ./doc/chapter2;BYTE                    (POSIX)

The keywords FIXED, VARIABLE, UNDEF and BYTE allow you to change the internal
structure of a file during an %ALTFILE or %COPY operation.  Note that these
keywords are mutually exclusive, that is, you may specify only one of these
keywords.  The same is true for BINARY and ASCII; however, either of these may
be combined with one of the previous keywords (i.e.  you can specify
";FIXED;ASCII" or ";BINARY;VARIABLE", but not ";VARIABLE;ASCII;BINARY" or
";BINARY;UNDEF;BYTE").

When converting files to FIXED or VARIABLE length, you have the option of
specifying the new fixed length or the maximum length using the ;REC= keyword.
Files that are converted to FIXED length will have trailing spaces (if ASCII)
or NULLS (for BINARY) appended to each record.  Files that are converted to
VARIABLE ASCII will have trailing spaces REMOVED unless the ;KEEPTRAIL keyword
is specified.


_ALTJOB_566
%ALTJOB

Syntax:   %ALTJOB userset; altjobparms
          [;NOVERIFY]
          [;QUIET]

Examples: %ALTJOB @.AP&WAIT; INPRI=4
          %ALTJOB WAIT; OUTDEV=LP2
          %ALTJOB REPORTJ,@.@; INPRI=12

The %ALTJOB command is an enhanced version of MPE's :ALTJOB command.  It allows
you to specify which jobs to alter using VESOFT usersets (see the Usersets
section of the SECURITY User Manual).  The ;NOVERIFY and ;QUIET parameters are
the same as those used in the %ABORTJOB command.  For more information, see the
documentation for the %ABORTJOB command.


_ALTPROC_567
%ALTPROC

Syntax:   %ALTPROC [[PIN=] [#P]pin | [PIN=](pin [ ,...  ])]
                   [[JOB=] userset | JOB=(jobID [ ,...  ])]
          [;PRI=  CS|DS|ES ]
          [;[NO]TREE]
          [;USER|ANYUSER]
          [;SYSTEM]

Examples: %ALTPROC #J232;PRI=CS
          %ALTPROC PIN=100;PRI=DS
          %ALTPROC BATCH-#J200;PRI=ES


MPE_V_and_MPE_iX_differences___ALTPROC_command_568
MPE/V and MPE/iX differences: %ALTPROC command
   Note: This command is only available on MPE/iX systems.

The %ALTPROC command is used to alter the priority of a process or processes.
MPEX's %ALTPROC command is an improved version of the MPE/iX :ALTPROC command.
The main enhancement is that it supports VESOFT usersets (see the Usersets
section of the Security User Manual for details) in the job specification.
Please refer to HP's documentation for an explanation of the various options.


_ALTSCHED_569
%ALTSCHED

Syntax:   %ALTSCHED scheduledjobset [schedparms]
          [;NOVERIFY]
          [;QUIET]

Examples: %ALTSCHED BACKUP,MANAGER.SYS; AT=23:00
          %ALTSCHED @.AP; IN=0,1,0
          %ALTSCHED MONDAY,PR.PROD; DAY=TUESDAY
          %ALTSCHED #J23; DATE=12/31/90
          %ALTSCHED MYJOB,USER.DEV;NOVERIFY


MPE_V_and_MPE_iX_differences___ALTSCHED_command_570
MPE/V and MPE/iX differences: %ALTSCHED command
Note: This command is only available on MPE/iX systems.  MPE/V release 3P
      contains support for altering the submission time of jobs in the SCHED
      and WAIT queues.

The %ALTSCHED command lets an SM user change the scheduling parameters of an
existing job in the SCHED state.  You can specify which jobs to re-schedule
using VESOFT usersets (see the Usersets section of the SECURITY User Manual for
details) and any MPE :STREAM scheduling parameters (AT=, DAY=, DATE=, IN=).
This is especially useful if you need to re-schedule a job that you no longer
have the source for, or a STREAMX job using parameter substitution (see the
SECURITY User Manual for details) and you don't know what parameters it was
:STREAMed with.

For example, if you have a job scheduled to run at 11:00 PM and decide you need
it to run at 10:00 PM instead, the command

   %ALTSCHED #J1234; AT=22:00

will re-schedule it for you.

Note that after a job has been re-scheduled by %ALTSCHED, it will have a new
job number.

Another use of %ALTSCHED is to immediately submit a scheduled job.  Since we
use normal MPE syntax for the new scheduling parameters, entering "%ALTSCHED
jobset" without any scheduling information will default to "stream it NOW".

By default, unless you specify a single particular job number, ALTSCHED will
show the job numbers and logon IDs of all the jobs that are to be re-scheduled
and then ask you if it's OK to process them.  If you do not reply "Y", the jobs
will not be re-scheduled.  This can help you avoid accidentally altering many
jobs that you don't actually want to alter.

If you want to do the %ALTSCHED without prompting for verifications, just
append ";NOVERIFY" to the command, e.g.

     %ALTSCHED @,MANAGER.SYS; AT=23:45; NOVERIFY

This will still show the numbers and logon IDs of the jobs that are being
processed; using the ";QUIET" keyword, e.g.

     %ALTSCHED @.AP; IN=0,1,0; QUIET

will turn off both the verification request and the display of the job numbers
and logon IDs.

As we mentioned above, if you specify a single job/session number (e.g.
"%ALTSCHED #J1234...") you will not be asked for verification, and the job
number/logon will not be displayed, just as if you had said ";QUIET".

NOTE: Due to current limitations, this command cannot alter "#A" type jobs
      (jobs streamed by the STREAMX scheduler), nor will it accept our extended
      submission syntax when re-submitting a job (this includes the ;REPEAT=,
      ;CHECKEVERY, and related keywords).


_ALTSEC_571
%ALTSEC


Altering_ACDs_of_an_entire_fileset_572
Altering ACDs of an entire fileset

Syntax:   %ALTSEC fileset; [altsecparms]

Examples: %ALTSEC PERS@.MGRMEMOS; (R,W,A,L,X:CR)
          %ALTSEC @.@.TELESUP(PROG.PMCAP); (R,X:AC;W,A,L:CR)
          %ALTSEC MYDB+MYDB?#; (R,W,A,L,X:AL,GU)
          %ALTSEC @.DATA(NOT HASACD); NEWACD=(R:@.PROD;W:MGR.PROD)
          %ALTSEC @.@.DEV; COPYACD=AP010.PUB.DEV

The %ALTSEC command lets you alter the security characteristics -- access masks
and ACDs -- of entire FILESETS.

Particularly useful applications include:

   * One of the troubles with :ALTSEC is that whenever you re-build a file
     (e.g.  using :EDITOR's /KEEP, which purges the target file and re-builds
     it), the security matrix is set back to READ, WRITE, APPEND, EXECUTE,
     LOCK: ANY, and any ACDs set up for the file are lost!

     Therefore, it's a good idea to regularly %ALTSEC filesets that you know
     should be specially protected, just in case somebody re-built one of those
     files and forgot to manually re-:ALTSEC it.  For example:

        %ALTSEC PERS@.MGRMEMOS; (R,W,A,L,X:CR)

or

        %ALTSEC PERS@.MGRMEMOS; NEWACD=(R,W:JOHN.MGRMEMOS)

   * MPEX's powerful selection criteria can be used to intelligently control
     security on specific files.  For instance:

        %ALTSEC @.@.TELESUP(ISPROG and PROG.PMCAP);&
                (R,X:AC;W,A,L:CR)

     will %ALTSEC all the privileged program files (PROG.PMCAP) in the TELESUP
     account to prevent anybody other than TELESUP users (and users with SM
     capability) from running them.

     Similarly, if you use ACDs, you can say

        %ALTSEC @.DATA(NOT HASACD and ISASCII); &
                NEWACD=(R:@.PROD;W:MGR.PROD)

     to alter all the ASCII files (ISASCII) in the DATA group that don't
     already have an ACD.

   * Finally, the %ALTSEC command works on databases (DBUTIL has >>RELEASE and
     >>SECURE commands, but no >>ALTSEC command).  Saying

        %ALTSEC MYDB+MYDB?#; (R,X,W,A,L:AL,GU)

     will alter the MYDB database so that only users in the same group or users
     with AL capability can access it.  Note, however, that only the access
     mask (not the ACD) features of %ALTSEC can be used on databases -- MPE
     doesn't let us define ACDs for databases.  However, the VEOPEN module of
     VESOFT's SECURITY product lets you restrict access to database not just by
     user ID (as ACDs would) but also by program, by session name, by mode, and
     by user class!  See Database Security in the SECURITY User Manual for
     details!

An additional advantage of MPEX's %ALTSEC is that it does not require creator
access when it is used to alter a file's access mask.  It can be used by
anybody with Read, Write, and eXecute access to a file (since anyone who has
Read, Write, and eXecute access can already do anything he pleases to the
file); this can be very useful when, say, the System Manager (or an account
manager) wants to %ALTSEC a whole fileset of files that may be in many
different accounts and may have been created by many different users.

The %ALTSEC alter-ACD options can be used only by a user with SM capability, a
user with AM altering files in his own account, or the file's creator -- this
is exactly the same as the requirements of MPE's alter-ACD options.


_ALTSPOOLFILE_573
%ALTSPOOLFILE


Device_class_of_spool_files__altering_574
Device class of spool files: altering


Output_priority_of_spool_files__altering_575
Output priority of spool files: altering


Number_of_copies_of_spool_files__altering_576
Number of copies of spool files: altering

Syntax:   %ALTSPOOLFILE spoolfileset; altspoolfileparms|spoolfparms [ ;...  ]

Examples: %ALTSPOOLFILE $STDLIST.@.@(SPOOL.JSNAME="MCOMPILE"); PRI=3
          %ALTSPOOLFILE RPTLIST.DEV.AP(SPOOL.NUMCOPIES=5); COPIES=1
          %ALTSPOOLFILE @.@.@(SPOOL.DEVICE="FASTLP"); DEV=LP; PRI=1
(MPE/iX): %ALTSPOOLFILE REPORT.PUB.PR; UNDEFER

The %ALTSPOOLFILE command is just like MPE's :ALTSPOOLFILE (and MPE/iX's
:SPOOLF command), except that:

   * It supports spool file filesets, letting you alter many spool files at
     once, WITHOUT having to know their #Oxxx numbers.

   * It can be performed not just by the console operator, but also by:

       - anybody with SM or OP capability,

       - anybody with AM capability working on spool files in his own account,

       - anybody working on his own spool files.

(Note that this is the same security system used by SPOOK5.)

As the examples above show, this can be an exceptionally powerful command, not
just because you can perform it on several spool files at once, but also
because you can indicate the spool file not by its (completely arbitrary) #Oxxx
number, but by its spool file name, creator job name, priority, etc.  For
instance,

   %ALTSPOOLFILE $STDLIST.@.@(SPOOL.JSNAME="MCOMPILE"); PRI=3

will find all the job $STDLISTs created by jobs with job name MCOMPILE and
alter their output priority to 3.  Without MPEX, you'd have to use SPOOK5 to
>TEXT each spoolfile in the system to find out their job names (which aren't
shown by SPOOK5 >SHOW), remember the #Oxxx numbers, and then alter them one by
one.


MPE_V_and_MPE_iX_differences__NM_spooler__ALTSPOOLFILE_577
MPE/V and MPE/iX differences: NM spooler %ALTSPOOLFILE
MPE/iX Native Mode Spooler Note:

The Native Mode Spooler on MPE/iX does not retain the spoolfile's group name.
If you specify a group name in %ALTSPOOLFILE on MPE/iX, it will be effectively
ignored.  For example,

   %ALTSPOOLFILE $STDLIST.PUB.PROD...

is the same as

   %ALTSPOOLFILE $STDLIST.@.PROD...


_BACKG_578
%BACKG

Syntax:   %BACKG
          [SHOW]
          [STARTJOB]
          [STOPJOB]
          [START|STOP, taskname]

          "taskname" is one of:
            ALARM   AUDITC    CMDPROT   HELLO    LOGOFF
            LOGON   NETPUSH   NETRECV   OBSFILL
           or the name of a user-implemented task.

Examples: %BACKG STARTJOB
          %BACKG START,LOGOFF
          %BACKG STOP,LOGOFF
          %BACKG SHOW
          %BACKG STOPJOB

A number of MPEX, SECURITY, and VEAUDIT features require a background task that
either runs continuously (ALARM, CMDPROT, HELLO, LOGOFF, NETRECV) or
periodically (NETPUSH, OBSFILL, AUDITC).  In order to help you better manage
your system, VESOFT provides a special facility that will execute all of these
tasks within a single background job!

NOTE: not all tasks shown here are available on all machines.  For instance,
the HELLO and LOGON tasks make use of an operating system feature that is
unavailable on CLASSIC systems and pre-4.0 XL systems.

The BACKG background job is controlled by an interactive command, which you can
enter through MPEX, SECURITY, or VEAUDIT (in these examples only, what you type
is underlined):

   :RUN MPEX.PUB.VESOFT
   %BACKG
or
   :RUN LOGON.PUB.VESOFT, SEC
   %SEC BACKG
or
   :RUN VEAUDIT.PUB.VESOFT, VEAUDITCMD
   %VEAUDIT BACKG

Note: for the sake of brevity, all examples will use MPEX; just remember that
you can use SECURITY or VEAUDIT for any of the BACKG commands.

The %BACKG command has options to start and stop the background job itself, and
to start, stop, and show the individual tasks being run by the background job.
(If you type %BACKG without any parameters, it does a SHOW.)

%BACKG STARTJOB  (requires SM or OP capability)


STARTJOB_579
STARTJOB

The easiest way to start the background job is to type:

     %BACKG STARTJOB

from the MPEX prompt.  MPEX will submit the job using the same technique that
STREAMX uses to insert passwords for MANAGER.VESOFT, so we require the user
starting the job to have SM or OP capability.  One advantage to using the
%BACKG STARTJOB command is that MPEX checks whether the background job is
already running before actually submitting the job.

Note that if you use the %ALARM command (documented in this manual) to set an
alarm and the BACKG job is not running, it will be started for you
automatically, but with only the ALARM task active.  If %BACKG STARTJOB is
subsequently issued, any other pending BACKG tasks will be started at that
time.

%BACKG STOPJOB


STOPJOB_580
STOPJOB

To stop the background job, type

     %BACKG STOPJOB

or use the :ABORTJOB command.  The advantage of using "%BACKG STOPJOB" is that
the job will terminate normally instead of being "ABORTED BY SYSTEM
MANAGEMENT".

Note: if you stop the background job using %BACKG STOPJOB without stopping each
individual task (using %BACKG STOP,task documented below) then each task will
be automatically re-started the next time you re-start the background job.
This makes it very convenient to be able to restart the BACKG job after your
system backup without having to remember which tasks were active at the time.
(Stopping the BACKG job for a backup is important because several of the tasks
may have control files or the SECURG file open while they run.  If these files
are in use, then the :STORE command may not store these files to tape, which
may subsequently cause problems if you need to recover your system using these
tapes.)

%BACKG START,taskname


START_581
START

This command tells the background job to begin execution of one of the tasks
under its control.  Some of the tasks will begin execution immediately, and
continue until you stop them (or stop the entire job).  Others will suspend
until their scheduled execution time, when they will execute once and then
suspend again until the next day.  We'll describe later exactly which ones do
what, and how you can control when the intermittent tasks are to execute.

Here are a few examples:

   %BACKG START,LOGOFF      (* to start LOGOFF *)
   %BACKG START,OBSFILL     (* OBSFILL will run once a day *)


Staskname_DATA_582
Staskname.DATA
Note: Because all of the tasks run in a single job, we re-direct the STDLIST
for each task to a file (named S + the taskname) in the DATA group (e.g.
SLOGOFF, SOBSFILL, etc.) -- otherwise, reading the $STDLIST of the BACKG job,
you wouldn't be able to tell which lines were printed by which tasks.

Each of these files is overwritten every time you restart the corresponding
BACKG task.

%BACKG STOP,taskname


STOP_583
STOP

This command tells the background job to stop executing the specified task.

Examples:

   %BACKG STOP,CMDPROT
   %BACKG STOP,AUDITC

Note: if you stop the background job but don't use %BACKG STOP to terminate a
particular BACKG task first, that task will be automatically re-started the
next time you re-start the background job.  For instance, if you have LOGOFF
running, and you stop the background job (by doing a %BACKG STOPJOB, :ABORTJOB,
etc.), LOGOFF will be stopped; however, the next time you start the background
job (e.g.  by doing a %BACKG STARTJOB), LOGOFF will be re-started
automatically.

%BACKG SHOW


SHOW_584
SHOW

This command shows you the current status of all available background tasks:
either "Initializing", "Executing", "Not Executing", or "Aborted".  If the
background job is not running, all tasks will show as either "Not Executing" or
"Pending".

In the case of intermittent tasks like OBSFILL that are usually "sleeping"
(waiting to execute at a future time) "Executing" means they will execute at
some future time; "Not Executing" means they will not execute.

%BACKG SHOW,taskname


SHOW_585
SHOW

This form of the %BACKG SHOW command will display the $STDLIST of a particular
task, whether or not the task is currently active.  The $STDLIST is stored in
the file 'S+taskname' in the DATA group.

BACKGINI.DATA CONFIGURATION FILE


BACKGINI_DATA_586
BACKGINI.DATA

Whenever you start the BACKG job, the first thing it does (before it starts any
of the background tasks) is to execute any commands in the file BACKGINI.DATA.
This can be used, for example, to issue a :FILE-equation for
LOGOFF.DATA.VESOFT, or to specify when the intermittent tasks (ALARM, NETPUSH,
OBSFILL, AUDITC) are to run by setting special variables (described below).

If you make any changes to BACKGINI.DATA, you must stop and then re-start the
BACKG job before the changes will take effect.

SETTING EXECUTION PRIORITY FOR BACKG TASKS


Setting_execution_priority_for_BACKG_tasks_587
Setting execution priority for BACKG tasks


ALARMPRI_588
ALARMPRI


AUDITCPRI_589
AUDITCPRI


CMDPROTPRI_590
CMDPROTPRI


LOGONPRI_591
LOGONPRI


HELLOPRI_592
HELLOPRI


LOGOFFPRI_593
LOGOFFPRI


NETPUSHPRI_594
NETPUSHPRI


NETRECVPRI_595
NETRECVPRI


OBSFILLPRI_596
OBSFILLPRI
If you want to have any of the background tasks execute at a higher (or lower)
priority than the default you have set for batch jobs, all you have to do is
add a

   SETVAR tasknamePRI "xS"

(where "taskname" is one of the background task names, and "xS" is the subqueue
[CS, DS, or ES] that you want that task to execute in) to your BACKGINI.DATA
file.  For example, if you want LOGOFF to run in the CQ, you would add the line

   SETVAR LOGOFFPRI "CS"

to your BACKGINI.DATA file.

BACKG TASKS


TASKLIST_BACKG_VESOFT_597
TASKLIST.BACKG.VESOFT
The file TASKLIST.BACKG.VESOFT contains a list of valid task names.  This file
will be updated as new tasks are developed by VESOFT.  Additionally, if you
decide that you do not want to use a particular task, you can remove it from
this list and it will be disabled.

Here are the tasks that can be run using %BACKG, plus notes on any
configuration options for them that you can put in BACKGINI.DATA:


ALARM_598
ALARM


VESOFTALARMPAUSE_599
VESOFTALARMPAUSE
ALARM     is the MPEX "alarm" facility (see the %ALARM command in this manual).
          By default, the ALARM task wakes up once per minute; you can change
          this (to, say, 5 minutes) by adding to your BACKGINI.DATA file:

         SETVAR VESOFTALARMPAUSE 300

          Note: The ALARM task is used by the STREAMX SCHEDULER to schedule
                repeating or conditional jobstreams.  If you intend to use this
                feature, the ALARM task must be active.


AUDITC_600
AUDITC


VEAUDITCTIME_601
VEAUDITCTIME
AUDITC    collects the information VEAUDIT needs to produce the reports on "MPE
          Passwords Unchanged In The Last 30 Days", "SECURITY Passwords
          Unchanged In The Last 30 Days", "Recent MPE Directory Changes", and
          "Recent SECURITY Users Changes".  AUDITC should be run daily.
          By default (if you've done a %BACKG START,AUDITC), it will be run at
          2AM.  To change this to 3:15AM, add the following line to
          BACKGINI.DATA.VESOFT:

         SETVAR VEAUDITCTIME "3:15AM"


CMDPROT_602
CMDPROT
CMDPROT   is the VEAUDIT facility which protects your UDC catalog,
          COMMAND.PUB.SYS.  It is described in the VEAUDIT User Manual under
          "Section #105: Users Who May Disable System UDCs".
          It runs continuously, but in a "MSG WAIT" state so it doesn't use any
          CPU time after starting up.


HELLO_603
HELLO
HELLO     is a %BACKG task that makes use of a Procedure Exits (PE) to
          automatically authorize network logons.  Starting this task enables
          the PE, and stopping the task disables the PE.  Note that this task
          must run continuously to trap logons from such products as ARPA and
          FTP which circumvent all UDCs (including any that use OPTION LOGON).
          See the SECURITY manual 'NETWORK SECURITY...' chapter for details.

          NOTE: as Procedure Exits are used, this task is only available on
          MPE/iX 4.0 and later systems.


LOGOFF_604
LOGOFF


LOGOFF_DATA_605
LOGOFF.DATA


LOGOFFAB_PUB_606
LOGOFFAB.PUB


LOGOFFWR_PUB_607
LOGOFFWR.PUB
LOGOFF    is SECURITY's facility for aborting idle sessions (a real security
          risk -- see "Unattended Terminal Security" in the
          SECURITY User Manual).
          By default, LOGOFF uses the files LOGOFF.DATA, LOGOFFAB.PUB.VESOFT,
          and LOGOFFWR.PUB.VESOFT; you may put file equations for any or all of
          these files in BACKGINI.DATA.VESOFT.  LOGOFF generally wakes up every
          five minutes, but its operation is controlled by the file
          LOGOFF.DATA.VESOFT.


LOGON_608
LOGON
LOGON     The LOGON task enforces SECURITY/3000 logon checking regardless of
          whether or not the UDC file LOGONUDC.PUB.VESOFT has been
          :SETCATALOGed (or ignored by SM users using the ;PARM=-1 option of
          the :HELLO command).
          This task makes use of a Procedure Exit (PE) that traps all logons
          and runs our LOGON program.  Starting this task enables the PE which
          will then continue to trap logons even if the BACKG job is aborted by
          the ABORTJOB command.  Stopping the task with the %BACKG STOP command
          will disable the trap and return your system to normal.

          NOTE: as Procedure Exits are used, this task is only available on
          MPE/iX 4.0 and later systems.


NETRECV_609
NETRECV
NETRECV   is part of the multi-CPU user profile maintenance facility of
          SECURITY (see the SECURITY User Manual).
          It runs continuously, but only uses CPU when there is a user profile
          change.


NETPUSH_610
NETPUSH


NETPUSHTIME_611
NETPUSHTIME
NETPUSH   is another option of the multi-CPU user profile maintenance facility
          of SECURITY.
          NETPUSH runs once a day to forward SECURITY user profile changes to
          other systems.  By default, %BACKG will run NETPUSH every day at 1AM
          (but only if you've entered a %BACKG START,NETPUSH).  If you want
          NETPUSH to run at 2:30 AM, add the following line to
          BACKGINI.DATA.VESOFT:

         SETVAR NETPUSHTIME "2:30AM"


OBSFILL_612
OBSFILL


OBSFILLTIME_613
OBSFILLTIME
OBSFILL   is part of SECURITY's MPE-password obsolescence facility; it collects
          all MPE password changes.
          OBSFILL runs once a day to see if any MPE passwords have been changed
          during the day.  By default (if you've done a %BACKG START,OBSFILL)
          it will be run at 1AM.  As above, if you want to run it at a
          different time simply add a line to BACKGINI.DATA.VESOFT, e.g.:

         SETVAR OBSFILLTIME "11PM"


_BREAKJOB_614
%BREAKJOB

Syntax:   %BREAKJOB userset
          [;NOVERIFY]
          [;QUIET]

Examples: %BREAKJOB @.AP
          %BREAKJOB @.@
          %BREAKJOB REPORTJ,@.@
          %BREAKJOB #J1234+#J1235

The %BREAKJOB command is an enhanced version of MPE's :BREAKJOB command.  It
allows you to specify which jobs to suspend using VESOFT usersets (see the
Usersets section of the SECURITY User Manual).  Of course, this command will
only apply to jobs that are in the EXEC state.  It uses the same parameters as
%ABORTJOB.  For more information, see the documentation for the %ABORTJOB
command.


_BYE_615
%BYE


BYE_616
BYE


QUIT_617
QUIT


ASK_618
ASK
Syntax:   %BYE [BYE|QUIT|ASK]

Examples: %BYE
          CPU=5.  Connect=1.  WED, DEC 13, 1995,  4:09 PM.

          %BYE QUIT
          END OF PROGRAM

          %BYE ASK
          OK to logoff (y/N)? n
          END OF PROGRAM

The %BYE command is a modified version of MPE's :BYE command.  It allows you to
terminate the current MPEX process, and also (on MPE/iX systems) to terminate
the current Session.  Like MPE's :BYE command, %BYE may not be used within
Jobs.

By default (or when the ;BYE keyword is specified), you will be logged off when
%BYE is executed.  If you specify the ;QUIT keyword, MPEX will terminate, but
the active session will not be logged off.  If you specify the ;ASK keyword,
then you will be prompted whether to log off or not.

%BYE always checks to see if MPEX has any active son processes (perhaps as a
result of using the %GOON command), and will fail if any active son processes
exist.  You must either wait for the active sons to terminate, or use the %KILL
command to terminate them before %BYE will succeed.

The VESOFTDEFAULTBYE variable may be used to change the default behavior of the
%BYE command.


VESOFTDEFAULTBYE_619
VESOFTDEFAULTBYE
To ensure that %BYE will terminate MPEX without also logging users off the
system, add the following line to your MPEXMGR.PUB.VESOFT file:

   %SETVAR VESOFTDEFAULTBYE ";QUIT"


VESOFTDEFAULTBYE_620
VESOFTDEFAULTBYE
To change %BYE so that users will be prompted whether they wish to logoff or
not, instead add the following line:

   %SETVAR VESOFTDEFAULTBYE ";ASK"

The ;BYE keyword allows you to override any VESOFTDEFAULTBYE setting, and
guarantees that your session will be terminated.


_CALC_621
%CALC

Syntax:   %CALC expression

Examples: %CALC 123*456+789
          56877, $DE2D, %157055, "...-"
             << output in decimal, hexadecimal, octal, and ASCII >>
             << ASCII has unprintable chars replaced by "." >>

          %CALC 456.0//5.8
          78.620689                     << real arithmetic >>

          %CALC TODAY+5
          93/02/04                      << date arithmetic >>

          %CALC STR("TESTING"+"ONE"+"TWO"+"THREE",6,12)
          NGONETWOTHRE                  << string manipulation >>

          %CALC MPEXNUMSUCCEEDED//(MPEXNUMFAILED+MPEXNUMSUCCEEDED)
          0.950000

The %CALC command evaluates an arbitrary expression (see Appendix for details
on expression syntax and the available operators).

The expression can involve integers, strings, logical values, real numbers,
dates, and times; it can also operate on MPEX VARIABLES (see the MPEX Variables
chapter) as well as on constants.

If the expression has an integer result, the result will be displayed in
decimal, hexadecimal, octal, ASCII representation of the 4 bytes, with
"garbage" (i.e.  unprintable) characters represented by periods (".").

In addition to displaying the result, %CALC also sets the HPRESULT variable to
the calculated value.


_CALENDAR_622
%CALENDAR

                    [monthname]
Syntax:   %CALENDAR [month]  [,year]
                    [@]
          [;NOHOLIDAY]
          [;PICTURE]

Examples: %CALENDAR FEB
          %CALENDAR OCTOBER,2004
          %CALENDAR 2,68;NOHOLIDAY
          %CALENDAR @;PICTURE

Prints a calendar for the given month (or for the whole year if month is given
as "@").  The month can be given as a number (e.g.  10) or as a string (e.g.
OCTOBER), optionally abbreviated to the first three letters (e.g.  OCT).  The
year may be entered as a two or four digit year.  The default month is the
current month; default year is the current year.  If you're printing the
calendar for the current month, then today's date will be highlighted.


NOHOLIDAY_623
NOHOLIDAY
Certain hard-to-remember holidays are automatically listed after the calendar.
If you don't want these holidays listed, simply add the keyword ;NOHOLIDAY.  If
you want %CALENDAR to not display the holidays by default, simply add the line

   %SETVAR VESOFTDEFAULTCALENDAR ";NOHOLIDAY"

to your MPEXMGR.PUB.VESOFT file.

(You can change which holidays are listed by creating your own files similar to
the HOLID##.DATA.VESOFT (HOLID01 through HOLID12) and issuing file-equations
for them.)


_CHGROUP_624
%CHGROUP

Syntax:   %CHGROUP [groupname [/grouppass]]
          [;KEEPCAPS]
          [;KEEPALLOW]
          [;KEEPUDCS]

Examples: %CHGROUP DATA
          %CHGROUP PUB; KEEPCAPS
          %CHGROUP

The %CHGROUP command (as you can probably guess) allows you to switch to a
different group.  If you don't specify which group to change to, you will be
changed to your home group.  If the new group has a group password (and you
don't include it in the %CHGROUP command), you will be prompted for it unless
you have SM or AM capability, or you are changing to your home group.


ISCHGROUPED_625
ISCHGROUPED
MPEX has a function called ISCHGROUPED() that returns TRUE if the user has
issued an MPEX %CHGROUP command and is currently in a different group to the
logon group.  After the %CHGROUP command is used to return to the original
logon group, ISCHGROUPED() returns FALSE.  This is more specific than the
ISCHLOGONED() function, which returns TRUE if the user has changed logons
directly (using %CHLOGON) or indirectly (using %CHGROUP).  In fact, using
%CHLOGON to change only the group will cause ISCHGROUPED() to return TRUE
(which is actually what %CHGROUP does internally).

One thing to be aware of with CHGROUP (and CHLOGON, for that matter) is that
the predefined variable HPGROUP will change to reflect the new group name.
What this means is that if you have:

   SETVAR MPEXPROMPT "!HPGROUP.!HPACCOUNT: "

or anything similar in your MPEXMGR start-up file, you should change it to:

   SETVAR MPEXPROMPT "!!HPGROUP.!!HPACCOUNT: "

so that when you issue the %CHGROUP command your prompt changes (otherwise your
MPEXPROMPT variable will remain set to the same value even though you changed
from one group to another -- see the discussion of "!"'s with regard to
variable substitution).

%CHGROUP is really just a subset of the more general %CHLOGON command,
documented later in this manual (please see the %CHLOGON command for an
explanation of the various parameters).  In particular, %CHGROUP is affected by
$CHLOGON-NOPASS, $CHLOGON-FORBID, and $CHLOGON-PERMIT in STREAMX.DATA and any
appropriate $LOGON-EXECUTE commands in SECURCON.DATA (just as if you had
entered a %CHLOGON command).

Also, just like with %CHLOGON, we must disable the [BREAK] key when you do a
%CHGROUP until you do a %CHLOGON with no parameters; simply entering a %CHGROUP
with no parameters will not re-enable break if you didn't originally log on to
your home group; %CHGROUP with no parameters switches you to your home group
(for compatibility with MPE/iX); %CHLOGON with no parameters switches you back
to your original logon.  Please read the "Important note for MPE/iX users" in
the %CHLOGON documentation.

Special note: although this feature is being described in the MPEX User Manual,
it is also available (to SECURITY users) within STREAMX jobs (via ::CHGROUP)
and in SECURITY menus.


_CHLOGON_626
%CHLOGON

Syntax:   %CHLOGON [[session,] user [/pass] .account [/pass] [,group [/pass]]]
          [;KEEPCAPS]
          [;KEEPALLOW]
          [;KEEPUDCS]
          [;SILENT]                                        (NEW)

          %CHLOGON abbreviated logon                       (NEW)

Examples: %CHLOGON DAVID,MANAGER.SYS
          %CHLOGON =,CLERK.PR;KEEPCAPS;KEEPALLOW;KEEPUDCS;SILENT
          %CHLOGON

Special note: although this feature is being described in the MPEX User Manual,
some of the features that can be used to control it (the $CHLOGON-xxx commands
in the STREAMX.DATA file), are only available to you if you are a user of both
MPEX and SECURITY.  This command is also available (to SECURITY users) within
STREAMX jobs (via ::CHLOGON) and in SECURITY menus.

The %CHLOGON command gives you the ability to switch to a different MPE
account, group, user, or session name without having to re-logon via the :HELLO
command! Why not just re-logon via :HELLO?

   * The :HELLO command creates an entirely new session.  You lose all of your
     file equations, variable settings, temporary files, REDO history, etc.
     %CHLOGON preserves all of this (and more!) for you.

   * Because it doesn't have to actually create an entire new session, %CHLOGON
     is much faster than :HELLO.

   * %CHLOGON can be used in command files, SECURITY menus, and in STREAMX as
     "::CHLOGON"!

   * %CHLOGON lets you KEEP all of the CAPabilities (;KEEPCAPS), ALLOWs
     (;KEEPALLOW), and UDCs (;KEEPUDCS) from your original logon in your new
     logon; this includes extra capabilities and ALLOWs acquired via the GOD
     program or SECURITY's $ALLOW facility.

   * Like STREAMX, %CHLOGON can be configured to not prompt for MPE and
     SECURITY user profile passwords.  This means you can set up a command file
     or menu (with OPTION NOBREAK, and to which the user doesn't even need read
     access, only execute) that logs on to another account, performs some task,
     then switches the user back to his original logon.  This is much more
     secure than giving him the passwords to an account he doesn't normally
     need to log on to.

As you can see, %CHLOGON (::CHLOGON in STREAMX, and CHLOGON in menus) uses the
same basic syntax as MPE's ":HELLO" command, but with a few special keywords
added and the "user.account" is optional -- if you don't specify a
"user.account", %CHLOGON simply switches you back to your original logon, the
one you entered at the ":HELLO" command.  This is especially useful in command
files, SECURITY logon menus, and STREAMX jobs: you can do a "CHLOGON
newuser.newacct", perform whatever task you want under the new logon, then do a
"CHLOGON" with no parameters to switch back to the original logon.

You may use an "=" in place of the session, user, account, and/or group names
to retain your current session, user, account, and/or group.

After you enter the %CHLOGON command, you will be prompted for the appropriate
MPE and SECURITY password(s) (unless you have SM, or AM and are changing to
another logon in the same account, or there is a $CHLOGON-NOPASS -- documented
below -- in effect for you), and then you will be switched to the new logon.

One thing to be aware of with CHLOGON (and CHGROUP for that matter) is that the
predefined variables HPGROUP and HPACCOUNT will change to reflect the new logon
ID.  What this means is that if you have:

   SETVAR MPEXPROMPT "!HPGROUP.!HPACCOUNT: "

or anything similar in your MPEXMGR start-up file, you should change it to:

   SETVAR MPEXPROMPT "!!HPGROUP.!!HPACCOUNT: "

so that when you issue the %CHLOGON command your prompt changes (otherwise your
MPEXPROMPT variable will remain set to the same value even though you changed
from one logon ID to another -- see the discussion of "!"'s with regard to
variable substitution).

The following special keywords may be used in the %CHLOGON command:


KEEPCAPS_627
KEEPCAPS
   ;KEEPCAPS tells %CHLOGON to give you the same capabilities under your new
   logon that you had under your old one (this includes any capabilities
   acquired via the GOD program).  Note: in order to prevent AM users in one
   account from getting AM in another account (where they might not normally
   have it), ;KEEPCAPS only works if you have SM capability.


KEEPALLOW_628
KEEPALLOW
   ;KEEPALLOW tells %CHLOGON to ALLOW you the same console commands that your
   were ALLOWed under your old logon (this includes global ALLOWs, :ALLOWs
   issued by the console operator, ALLOWs acquired via the GOD program, and
   $ALLOWs in your SECURITY SECURCON.DATA file).


KEEPUDCS_629
KEEPUDCS
   ;KEEPUDCS tells %CHLOGON to give you the same UDCs under your new logon that
   you had under your old one.


SILENT_630
SILENT
   ;SILENT tells %CHLOGON to switch to the new logon without displaying the
   message "Welcome! You are now signed on".  This is useful when you want to
   use %CHLOGON within a command file or menu where the user does not need to
   know that you changed their logon-ID.


ISCHLOGONED_631
ISCHLOGONED


ISCHLOGONED_632
ISCHLOGONED
The function ISCHLOGONED() will return TRUE if the current session has executed
a %CHLOGON (and has not yet switched back).  This can be useful within a
command file or SECURITY menu to test the CHLOGON status.  In addition, the
ISCHGROUPED() function returns FALSE if the %CHLOGON command changes the
account or user, but TRUE if ONLY the group changed (which is actually what
%CHGROUP does internally).

ELIMINATING PASSWORD PROMPTS ($CHLOGON-NOPASS)


_CHLOGON_NOPASS_633
$CHLOGON-NOPASS
You can allow particular usersets, using particular MPEX command files/SECURITY
menus/STREAMX jobs, to switch to particular logons without being prompted for
passwords by adding entries of the form:

   $CHLOGON-NOPASS  currentuserset  fileset  targetuserset

to your STREAMX.DATA file (as you can see, this is quite similar to the $NOPASS
and $WITHCAPS-PERMIT/FORBID entries in STREAMX.DATA).  For example,

   $CHLOGON-NOPASS  @.DEV  TESTPROD.CMD.PROD  TEST.PROD

means anyone in the DEV account can %CHLOGON to TEST.PROD with ANY session name
by using the command file TESTPROD.CMD.PROD.

The "fileset" above can include $STDIN; this is how you keep from asking for
passwords when the user enters "%CHLOGON..." directly from the MPEX "%" prompt.

RESTRICTING WHO MAY USE %CHLOGON ($CHLOGON-FORBID|PERMIT)


_CHLOGON_FORBID_634
$CHLOGON-FORBID


_CHLOGON_PERMIT_635
$CHLOGON-PERMIT
What if you don't want certain users to have access to %CHLOGON at all? There
are two keywords you can put in the STREAMX.DATA file to control who can use
%CHLOGON:

   $CHLOGON-FORBID  currentuserset  fileset  targetuserset
   $CHLOGON-PERMIT  currentuserset  fileset  targetuserset

By default, all users are allowed to use %CHLOGON to switch to any logon that
they know the passwords for.  $CHLOGON-FORBID lets you forbid a particular
userset from switching to a particular set of new logons via a particular
fileset of MPEX command files, SECURITY menus, and/or STREAMX jobs.  This
"fileset" can include (or exclude) $STDIN; this is how you control use of
"%CHLOGON..." in an interactive session.  $CHLOGON-PERMIT cancels the effect of
a previous $CHLOGON-FORBID.  This lets you say things like

   $CHLOGON-FORBID  @.PROD  @.@.@  @.@
   $CHLOGON-PERMIT  BERT,@.PROD  @.MUPPET.PROD  ERNIE,@.PROD

which means no users in the PROD account may use %CHLOGON at all, except any
user in PROD with a session name of "BERT" can use any file in the group
MUPPET.PROD to %CHLOGON his session name to "ERNIE".  Another example would be:

   $CHLOGON-FORBID  @.@          @.@.@  @.@
   $CHLOGON-PERMIT  @.DEV   $STDIN.@.@  @.@

Which means that only the users who can use the %CHLOGON command are users in
the DEV account, and even then, they can only use it from a "%" prompt.


CHLOGON_and_SECURITY_menus_636
CHLOGON and SECURITY menus

What if the new logon is protected by a SECURITY logon menu?

   * If you have SM capability (and use ;KEEPCAPS), you will be switched to the
     new logon and the menu will not be activated;

   * If you don't have SM capability, you will not be permitted to switch to
     the new logon at all.


_CHLOGON_OKMENU_637
$CHLOGON-OKMENU
If you want non-SM users to be able to switch to logons that are protected by
SECURITY logon menus (bypassing the logon menu), add the keyword

   $CHLOGON-OKMENU  currentuserset  fileset  targetuserset

to your STREAMX.DATA.VESOFT file.  This keyword only allows a user to bypass
the logon menu for the new logon if he knows the passwords (or if you also have
a $CHLOGON-NOPASS for him).

For example,

   $CHLOGON-OKMENU KENT,OPERATOR.SYS BOOTH.CMD.SYS BOSS,MANAGER.SYS

means "the user KENT,OPERATOR.SYS can use the command file BOOTH.CMD.SYS to
CHLOGON to BOSS,MANAGER.SYS, even if BOSS,MANAGER.SYS is protected by a logon
menu (the logon menu will be skipped)."

What if you want the user to be in the menu when he switches to the new
account? Easy! Using the same example as above, BOOTH.CMD.SYS could look
something like this:

   OPTION NOBREAK
   CHLOGON BOSS,MANAGER.SYS
   FILE MENUFILE=BOSS.MENU.SYS
   RUN MAIN.PUB.VESOFT,MENU
   CHLOGON


_CHLOGON__638
%CHLOGON
In addition to the STREAMX.DATA keywords of $CHLOGON-NOPASS, $CHLOGON-FORBID,
and $CHLOGON-PERMIT, %CHLOGON (and %CHGROUP) will also execute $LOGON-EXECUTE
commands from SECURCON.DATA as well.  Please refer to the SECURITY manual
discussion of $LOGON-EXECUTE for details on this keyword.

USING ABBREVIATED LOGONS WITH %CHLOGON


USING_ABBREVIATED_LOGONS_WITH__CHLOGON_639
USING ABBREVIATED LOGONS WITH %CHLOGON

If you have configured abbreviated logons for the LOGON facility of our
SECURITY package, then %CHLOGON will automatically recognize and use these
abbreviated logons just as if you had typed the entire logon string manually.
Abbreviated logons are only available when the BACKG job is running and the
HELLO task is active.  See the Additional Benefits of the VESOFT HELLO trap
section of the SECURITY manual for details on abbreviated logons and the HELLO
trap.

IMPORTANT NOTES FOR MPE/iX USERS


MPE_V_and_MPE_iX_differences___CHLOGON_command_on_MPE_iX_640
MPE/V and MPE/iX differences: %CHLOGON command on MPE/iX

Due to MPE/iX limitations we cannot change your logon ID for other processes in
your process tree, including your father process, other son processes of your
father (brother processes), and any of your son processes that existed before
you did the %CHLOGON (created, perhaps, by the %GOON or %SPOONFEEDing
facilities, or programs like QEDIT that suspend themselves, or by using MPEX
HOOKed programs).

Not changing your father process is only a problem if the father is still
active (VERY unusual).  Not changing your sons and "brothers" is a problem IF
they remain active, or you reactivate one of them to do something.  An example
of this would be if you were to, within MPEX, run QEDIT, suspend it, %CHLOGON,
re-activate QEDIT, and try and edit files.

For this reason, on MPE/iX systems, we do the following:

   * If you have any son processes MPEX will not allow you to do a %CHLOGON.
     You must first %KILL your son processes.

   * When you do a %CHLOGON,  we disable the <BREAK> key until you switch you
     back to your original logon.

   * If you exit MPEX (or STREAMX) without switching back to your original
     logon first, we switch you back automatically.

IMPORTANT NOTES FOR MPE/V USERS


MPE_V_and_MPE_iX_differences___CHLOGON_command_on_MPE_V_641
MPE/V and MPE/iX differences: %CHLOGON command on MPE/V

On MPE/V systems, using the %CHLOGON command completely switches you to a new
logon, just as if you had entered an MPE :HELLO command, with one exception: if
you exit MPEX without changing back to your original logon, you will remain in
that "changed" logon but have the UDCs you had in your original logon.

As long as you remain in MPEX (and assuming you didn't specify the ;KEEPUDCS
options), you will have the UDCs that are set for your current logon.

If you don't want to accidentally exit MPEX and have the "wrong" UDCs, you can
use the "%SET CHLOGONRETURN" command; this will make MPEX switch you back to
your original logon automatically when you exit (just like it does on MPE/iX --
see above).  Please see the documentation for this command later in this
manual.


_COMPRESS__DECOMPRESS_642
%COMPRESS/%DECOMPRESS

Syntax:   %COMPRESS   fileset
          %DECOMPRESS fileset

Examples: %COMPRESS @.SOURCE
          %COMPRESS MYBASE@.DEV(SECTORS>16)
          %DECOMPRESS @.ARCHIVED(INTCODE=1001)

COMPRESS/3000 is a file compression utility produced by RIGHT! software
company.  The %COMPRESS and %DECOMPRESS commands give you quick and easy access
to this software, provided, of course, that it is installed on your system.

The COMPRESS/3000 product allows you to compress all MPE files: KSAM files,
"flat" files, IMAGE databases, USLs, programs, and VPLUS forms to name a few.
Through a special agreement with RIGHT!, we can provide a demo version of
COMPRESS/3000 for you to evaluate (contact your sales representative for
details).


_COPY_643
%COPY

Syntax:   %COPY fromfileset [,tofileset]
          [;altfileparm] [ ;...  ]
          [;YES|NO|ASK]
          [;KEEPATTR]
          [;KEEPAMDATES]
          [;KEYFILE= keyfileset]
          [;DEV= [[[remotesystemname]#] devicename]
          [;COPYACD]
          [;BUFFERSIZE= nnn]
          [;CREATE[Q]]                                     (POSIX)

Examples: %COPY @.@.AP, @/=.@.APBACKUP; KEEPATTR; KEEPAMDATES
          %COPY APDB@, DBNEW@; DEV=3
          %COPY @.DEV, @.SOURCE; ASK
          %COPY K@.DATA, N@.DATA; FLIMIT=EOF*1.5; BLKFACT=BEST
          %COPY KSAMFILE, NEWDATA.NEWG.NEWA; KEYFILE=NEWKEY.NEWG.NEWA
          %COPY APDB@, =; DEV=SYSB#       << to another system >>
          %COPY APDB@, =; DEV=#           << back to the host system >>

          %COPY ./source/project-3/, ./archive/= ;CREATEQ  (POSIX)
          %COPY MPEFILE, /posixdir/posixfile ;BYTE         (POSIX)
          %COPY ./MyDir/MyFile, /YOURACCT/YOURGRP/YourDir  (POSIX)
                (Copies "MyFile" to "/YOURACCT/YOURGRP/YourDir/MyFile")

The %COPY command allows you to:

   * Copy filesets (temporary or permanent);

   * Copy IMAGE databases and KSAM files;

   * Do all copies (even those of databases and KSAM files) very fast;

   * Copy things into other accounts (if you have SM capability);

   * Specify new file parameters for the newly-built files (e.g.  DEV=3 or
     FLIMIT=EOF*1.5 -- all of these are the same as those permitted by the
     %ALTFILE command);

   * Copy files (including IMAGE databases!) to other HP3000 systems across
     dslines.
   * Copy files between MPE and POSIX directories, changing the format from
     FIXED, VARIABLE, or UNDEFined to BYTEstream (or the other way around) as
     needed.
   * Create a new POSIX directory when copying files, avoiding the need to
     manually build a complex directory structure.

This command copies all the files in "fromfileset" into correspondingly-named
files in "tofileset".  On systems that support POSIX, if the "tofileset" is a
subdirectory, then the files are copied into that subdirectory with the same
name as the original.  If you would like to copy a file to a back-referenced
file (prefixed by "*"), you should use the %FCOPY or %PRINT command instead.

WHAT IF THE "TO-FILE" ALREADY EXISTS? (;YES|NO|ASK)

   * If the ;YES keyword was specified, the old to-file will be purged.

   * If the ;NO keyword is specified, the old to-file will be kept and the copy
     (of this file) will not be done.

   * If the ;ASK keyword is specified, the user will be asked what he wants to
     do with the old to-file -- purge it or not purge it.

   * Default is ;ASK online, ;YES in batch.

HOW IS THE "TO-FILE" BUILT?

By default, the to-file is built by FOPENing it with the same "vital
attributes" (device class, FLIMIT, etc.) that the from-file has.  This means
that the to-file will have the same attributes except for:

   * the creator ID (which is set to the copying user's user ID);

   * the creation/restore/access/modify dates and times (which are set to the
     current date and time);

   * the file security (which is set to the system default -- :SECUREd,
     file-level access mask (R,A,X,W,L:ANY));

   * the lockword, which is set to whatever is specified in the "to-fileset".


KEEPATTR_644
KEEPATTR
If you specify a ;KEEPATTR on the %COPY command, the creator ID, the security,
and the creation and restore dates won't be changed.  All the to-file's
attributes except for

   * the last modify and access dates and times and

   * the lockword

will be the same as the from-file's.  If you want to also make the last modify
and access dates and times be the same as from-file's, specify BOTH a ;KEEPATTR
keyword and a ;KEEPAMDATES keyword.  (Note that neither ;KEEPATTR nor
;KEEPAMDATES will work if you're copying to another system, since we can't
change the file label of a remote file.  However, ;KEEPAMDATES will still
preserve the last access date of the from-file.)


_COPY_using__ALTFILE_keywords_645
%COPY using %ALTFILE keywords
You may also use any %ALTFILE keyword to explicitly change any attribute of the
target file.  For instance, saying

   %COPY APDB@, DBNEW@; DEV=3

will copy all the files whose names start with APDB (presumably the APDB
database) into files where the APDB is replaced by DBNEW; but all the to-files
will be built on device 3.

Similarly,

   %COPY K@.DATA, N@.DATA; FLIMIT=EOF*1.5; BLKFACT=BEST; EXTENTS=32

will copy K@.DATA into N@.DATA, setting the new files' file limit, blocking
factor, and maximum number of extents to the values specified.  Note that these
parameters are exactly identical (in syntax and in meaning) to the %ALTFILE
command parameters.

This feature, along with the new %ALTFILE keywords of FIXED, VARIABLE, UNDEF,
and BYTE will be most useful for systems that support POSIX.  Most MPE editors
and utilities expect FIXED or VARIABLE length records and may corrupt
BYTEstream files.  POSIX utilities and programs, on the other hand, will return
an error when attempting to read FIXED or VARIABLE files and will only create
BYTEstream files as output files.  When using the %COPY command to move files
between MPE groups and POSIX subdirectories, you will almost always want to add
either ;FIXED, or ;VARIABLE, or ;BYTE to convert the file format as you copy.
(Note, however, that this will slow down the speed of the %COPY command).

SPECIAL NOTE ON PRIVATE VOLUMES

Because the %COPY command is intended to make an exact copy of the file,
preserving virtually all attributes of the file (which is normally what you
want it to do), problems may arise (involving the device class specification)
when trying to %COPY a file to/from an account residing on a private volume set
to/from an account on the system volume set or a different private volume set.
Fortunately, you can easily get around the problem by using the ;DEV= keyword.
For example,

     %COPY @.PVGROUP.PVACCT, =.MYGROUP.SYSVOL; DEV=DISC

COPYING INTO OTHER ACCOUNTS

The %COPY command lets users with SM capability copy files into other accounts.
For instance, the

   %COPY @.@.AP, @/=.@.APBACKUP; KEEPATTR

command will copy all the files in the AP account into the APBACKUP account
(assuming all the appropriate groups are already built in the APBACKUP
account).  What can we say about this command?

   * If the person executing it has SM (perhaps by running GOD.PUB.VESOFT),
     it'll work even if he's not logged on to the APBACKUP account.

   * The target fileset is specified not as "@.@.APBACKUP" but as
     "@/=.@.APBACKUP".  If we'd said "@.@.APBACKUP", this would mean that the
     to-files would be built without lockwords (much like an ordinary :FCOPY...
     ;TO=file.group.acct will always build the ;TO= file without a lockword,
     even if the ;FROM= file has a lockword).


__646
=

     Specifying a "/=" after the to-filename ("@") means that all to-files are
     to be built with the same lockword as their corresponding from-files.
     Actually, we could have specified any lockword, e.g.  "@/FOO.@.APBACKUP"
     -- this would build all target files with lockword FOO.  However, this is
     usually not as useful as saying "@/=.@.APBACKUP".

   * We said ;KEEPATTR, telling MPEX to retain the creator ID, the security
     information, and the create and restore dates and times.  This is often a
     very good idea for such "bulk" copies.

     Note that if we hadn't said ;KEEPATTR, all the to-files would have the
     creator ID equal to the copying user's user ID.  This might cause problems
     if such a user doesn't exist in the target account.

COPYING DATABASES


IMAGE_databases__copying_647
IMAGE databases: copying

Databases can be copied with the %COPY command just like ordinary MPE files,
e.g.

   %COPY APDB@, DBNEW@; DEV=3

In order to copy a database, you must be logged on as the creator of the
database, the account manager of the account containing the database, or (if
you are copying to or from another account), as the system manager.
Internally, MPEX has to do a little bit of work to make sure the root file
remains consistent, but you'll never have to see it.  Database copies work well
and quickly.  (Of course, you shouldn't try to %COPY an open database -- it
won't corrupt the original database, but it is quite likely that the copy will
have broken chains or other errors).

COPYING KSAM FILES (;KEYFILE=)


KSAM_files__copying__648
KSAM files: copying


MPE_V_and_MPE_iX_differences___COPYing_CM_KSAM_files_649
MPE/V and MPE/iX differences: %COPYing CM KSAM files
Note: the following discussion relates to Compatibility Mode KSAM files only.
      Native Mode KSAM files (which no longer have a separate keyfile) are
      treated by MPEX the same as other files.

The %COPY command can copy KSAM files (very quickly, in fact).  For example, if
you say

   %COPY @.DATA, @.NEWDATA

and there happen to be some KSAM files in the DATA group, they'll be copied
into the NEWDATA group just as normal files would be.

However, remember that a KSAM file is actually not one file, but two (the data
file and the key file).  How does MPEX figure out what name to assign to the
new key file?

In the "%COPY @.DATA, @.NEWDATA" example, the answer is simple -- since the
to-file file names should be the same as the from-file file names (except for
the different group name), MPEX will build the new to-keyfile with the same
name as the old from-keyfile.  Similarly, if you say

   %COPY DEV@.PUB, PROD@.PUB

and there's a KSAM file called DEVDATA.PUB with key file DEVKEY.PUB, MPEX will
copy it into a file called PRODDATA.PUB with key file PRODKEY.PUB.

However, what if you just say

   %COPY OLDDATA, NEWDATA.NEWGRP

-- how can MPEX figure out a new name for the to-keyfile? It can't, which is
why in this case it requires that you specify the to-keyfile name explicitly:


KEYFILE_650
KEYFILE

   %COPY OLDDATA, NEWDATA.NEWGRP; KEYFILE=NEWKEY.NEWGRP

In general, whenever you copy a single KSAM file (rather than a fileset), you
should specify the ;KEYFILE= parameter.

There are also some other cases in which MPEX can't figure out the to-keyfile
name.  For instance, say that your data file is called DATAAP, your key file is
called KEYAP, and you enter the command

   %COPY DATA@, NDATA@.NEWSTUFF

How can MPEX figure out the to-keyfile name? Again, it can't -- in fact, MPEX
can only figure out the  to-keyfile name automatically when the from-keyfile is
itself part of the from-fileset OR when the to-fileset contains an "=" (e.g.
"%COPY DATA@, =.NEWSTUFF", in which case MPEX will know to keep the same file
name but put the file into the NEWSTUFF group).

In the "%COPY DATA@, NDATA@.NEWSTUFF" case, you again have to use the ;KEYFILE=
parameter, e.g.

   %COPY DATA@, NDATA@.NEWSTUFF; KEYFILE=NKEY@.NEWSTUFF

Now MPEX will know to copy DATAAP into NDATAAP.NEWSTUFF and build the key file
as NKEYAP.NEWSTUFF.

COPYING TO OTHER COMPUTERS (;DEV=envid#)


DEV_651
DEV
By specifying a DS device or an NS environment ID (followed by a #) as a DEV=
parameter, you can copy filesets (including databases!) to other systems over
DSLINEs or LANs.  (You can not, however, copy files from other systems -- you
must run MPEX on the system you wish to copy from.) For instance, you can say:

   %REMOTE:SYSB HELLO KIMBERLY,MANAGER.PROD
   %COPY MYDB@, =; DEV=SYSB#

This will copy files in the fileset MYDB@ (presumably a database root file and
its datasets) into files with the same name on the system accessed with the
SYSB DSLINE.

Special note: if you do the :REMOTE HELLO before running MPEX, you will need to
enter a %DSLINE command within MPEX before you can do the COPY; i.e.

   :REMOTE:SYSB HELLO KIMBERLY,MANAGER.PROD
   :RUN MAIN.PUB.VESOFT
   %DSLINE SYSB
   %COPY MYDB@, =; DEV=SYSB#


BUFFERSIZE_652
BUFFERSIZE
If you have problems, you might also try specifying the ;BUFFERSIZE= keyword:

   %COPY MYDB@, =; DEV=SYSB#; BUFFERSIZE=2048

to control the number of words we try to copy at a time (the default is 4096 --
it's possible that smaller numbers might work better over DS).

Also note that when you copy to a remote machine, the account into which you're
copying should be your remote logon account.  Non-remote %COPY can copy across
account boundaries, but remote %COPY can't (because of MPE restrictions).

PRESERVING LAST ACCESS/LAST MODIFY DATES (;KEEPAMDATES)


KEEPAMDATES_653
KEEPAMDATES
When you %COPY a file, the from file's last access date is set to today's date
(because the file is, after all, being accessed); this is the same as MPE/iX's
:COPY command does.

However, sometimes you do not want the last access date to be updated -- you
might want to use it for archival purposes, periodically saying something like

   %MPEXSTORE @.@.@-@.@.SYS-@.@.TELESUP(ACCDATE<TODAY-180);*TAPE;PURGE

to clean up your system and save disc space.  If you do this, you'd like to
update the last access date as rarely as possible -- update it only when
somebody actually tries to access the file for something productive.  If you
merely say

   %COPY @.@.AP,@/=.@.APBACKUP

you don't want all the AP account files to be marked as having been accessed
today.

If you say

   %COPY @.@.AP,@/=.@.APBACKUP;KEEPAMDATES

then MPEX will do the copy without updating the from-file's last access date.
If you want this to be the standard behavior of the %COPY command, you can say


MPEXCOPYKEEPAMDATES_654
MPEXCOPYKEEPAMDATES

   :SETJCW MPEXCOPYKEEPAMDATES=1

-- this tells MPEX that the %COPY command should never update the last access
and last modify dates of files even if ;KEEPAMDATES is not specified.  If
you're going to use this SETJCW command, you should probably put it into the
MPEXMGR.PUB.VESOFT file so that it comes into effect for all users in the
system.

If you specify both the ;KEEPATTR and the ;KEEPAMDATES keywords, e.g.

   %COPY @.@.AP,@/=.@.APBACKUP;KEEPATTR;KEEPAMDATES

then the to-file's dates (access, modify, create, and restore) will all be set
to be exactly the same as the from-file's dates.  A normal ;KEEPATTR without a
;KEEPAMDATES would set the to-file's create and restore dates to be the same as
the from-file's, but will make the to-file's access and modify dates be today's
date.

If you specify ;KEEPAMDATES without ;KEEPATTR, all of the to-file's dates will
be set to today's date (since the to-file is, after all, being created today)
-- however, the from-file's last access date will still be preserved (on the
from-file).

Note that for technical reasons, MPEX will always update the last access and
modify dates of a KSAM key file when a KSAM file is %COPYd.  We may remove this
restriction in the future, but for the moment it exists.

PRESERVING ACDs (;COPYACD)


COPYACD_655
COPYACD
Using Access Control Definitions (ACDs), MPE permits you to define exactly who
is authorized to access a particular file in a particular way.  You can, using
the :ALTSEC command, impose an ACD on a file (MPEX's %ALTSEC command lets you
do this to multiple files) -- this ACD can indicate that, say, JOE.PROD can
read and write to this file, while CLERK.PROD and MGR.AP can only read it, and
no other users can access it in any way.

The ;COPYACD keyword of the %COPY command lets you copy a file's ACD together
with the file, so that the newly-created file has the same ACD as the original.
(The default, just as in MPE's :FCOPY, is to build the new file without any
ACDs.) Thus, if you want to copy an entire group of files while preserving all
their attributes (including lockword, creator ID, access dates, and ACDs), you
can say

   %COPY @.DATA,@/=.NEWDATA;KEEPATTR;KEEPAMDATES;COPYACD

If the %COPY command encounters a file that has no ACD, it will copy it without
an ACD; if, however, it encounters a file whose ACD you are not authorized to
read (because you weren't granted RACD access to this file), %COPY will refuse
to copy the file.  This way you'll never be surprised by a file suddenly
"losing" its ACD.

THE %COPY COMMAND'S SPEED

The %COPY command is not only much more powerful than FCOPY -- it's much
faster, too.  It copies all files (MPE, KSAM, and IMAGE) via MR NOBUF, which is
a very efficient copying mechanism.

Unfortunately, there are a few cases in which MR NOBUF copies can not be used;
the %COPY will still work, but might take a long time:

   * If you're copying a file with the ;BLKFACT= keyword (specifying a
     different blocking factor for the to-file than the from-file).

   * If you're copying a KSAM file with the ;FLIMIT= or ;BLKFACT= keywords
     (changing the blocking factor or expanding the file limit of the new
     file).

   * If you're copying a file whose block size is not an even multiple of 128
     words.  If your file has record size 128 words, it's OK; if it has record
     size 40 words and blocking factor 16, it's also OK (since 16*40 = 640 is
     an even multiple of 128).  However, if your file has record size 40 words
     and blocking factor 3, the copy will be much slower (since 3*40 = 120, not
     an even multiple of 128).

These restrictions are placed on us by MPE/V; fortunately, more often than not
they don't apply, and fast MR NOBUF copies can be done.

COPYING SINGLE FILES

One other thing that you can do to make %COPYs of single files even faster is
to prefix "COPY" with a ":", e.g.

   %:COPY MYFILE,TOFILE;YES

Prefixing %COPY with a : tells MPEX that this is a single-file-only command;
MPEX can then save some of its fileset processing overhead.  However, this
means that the from and to-files must be ordinary MPE filenames -- no filesets,
selection conditions, "="s in the to file, etc.  Also, the ;BLKFACT= and
;FLIMIT= keywords can not be used on a %:COPY command.

LOCKWORDS AND %COPY


Lockword__on_the__COPY_command_656
Lockword: on the %COPY command

As we discuss in the MPEX And Your System Security section, MPEX is quite
intelligent in its lockword handling.  If you have SM capability (or AM
capability in your own account), MPEX will automatically supply the lockword
for each file being processed.  This lets you say something like:

   %COPY @.OLDGROUP,@.NEWGROUP

without having to specify the lockword of every lockworded file in OLDGROUP.

However, if you execute this %COPY command, what happens to all the lockwords
of the files being copied?

Well, remember that we must stay compatible with MPE's :FCOPY command (as well
as with :RENAME and with MPE/iX's :COPY).  If you say (in MPE)

   :FCOPY FROM=MYFILE/SECRET.OLDGROUP;TO=MYFILE.NEWGROUP;NEW

then MYFILE will be copied from OLDGROUP into NEWGROUP BUT THE THE NEW FILE
WON'T HAVE A LOCKWORD.  Don't blame us -- this is how MPE does it; if the
target filename does not include a lockword, the new file will be unlockworded.

Therefore, if you say

   %COPY @.OLDGROUP, @.NEWGROUP

MPEX will interpret this to mean "copy the OLDGROUP files into files in
NEWGROUP without lockwords" (just like MPE's :FCOPY).

What if you want to keep the lockwords? No problem! Just say

   %COPY @.OLDGROUP, @/=.NEWGROUP

The "=" in the lockword field means "keep the same lockword as the old file"
(see "Target Filesets" in the MPEX Filesets chapter for more information on
"=").

Therefore, when MPEX issues the :COPY command for each file in @.OLDGROUP it'll
be certain to include the old file's lockword (if any) on the new filename.
Instead of saying the equivalent of

   :FCOPY FROM=MYFILE/SECRET.OLDGROUP;TO=MYFILE.NEWGROUP;NEW

it'll say

   :FCOPY FROM=MYFILE/SECRET.OLDGROUP;TO=MYFILE/SECRET.NEWGROUP;NEW

and all the lockwords will be preserved.

COPYING DATA INTO EXISTING FILES


Appending_to_existing_files_657
Appending to existing files

As you see, the %COPY command is really useful for copying files into new files
-- it won't, say, append a file to an already existing file, or fill an
existing KSAM file with data from an MPE file.  If %COPY finds that the target
file already exists, it will either fail (if you specify ;NO) or purge the
existing file (if you specify ;YES).

If you want to copy data into existing files, we recommend that you use the
%FCOPY command (see below).

With the help and cooperation of several other vendors, we are able to provide
MPEX with the ability to change the capacity of IMAGE databases using their
products.  Note that since these other vendors are developing their programs
independently of VESOFT, Inc., they may make changes to their programs that
MPEX won't recognize.  While we do our best to ensure that we are using the
current syntax of their commands, we cannot guarantee this will always be the
case.

To use any of these commands to change a database's capacity, you must be
logged on as the database creator (in the same account as the database), and
you must have Read, Write, and Lock access to the database.  If you do not meet
these conditions, the %DBxxxALT command will try to stream a job for you (via
the MPEX %SUBMIT command) that logs on as the database creator and does the
capacity change.  You will be prompted for the passwords as appropriate.

Note: if your copy of database utility is not in the default group and account
where it is normally installed, you should add one of the following SETVAR
commands to your MPEXMGR.PUB.VESOFT initialization file to inform our software
of the location of your database utility:

   SETVAR MPEXDBADGFILE "ADAGER.group.account"   (for ADAGER)
   SETVAR MPEXDBGENFILE "DBGENRL.group.account"  (for DBGENERAL)
   SETVAR MPEXDBMGRFILE "DBMGR.group.account"    (for DBMGR)


_DBADGALT_658
%DBADGALT

Syntax:   %DBADGALT dbfileset, ratio

Examples: %DBADGALT @.DB, .50
          %DBADGALT @.DB (DBSETFULLNESS>.8 and MODDATE>TODAY-30), 0.6

The %DBADGALT command uses ADAGER to change the capacity of IMAGE datasets so
that they are a given percentage full (this command will only work if you own
ADAGER, the "Adapter/Manager for IMAGE Databases", a product of Adager).

For instance, the command in the above example increases the capacity of all
data bases in the DB group that are currently greater than 80% full so that
they are only 60% full.


_DBGENALT_659
%DBGENALT

Syntax:   %DBGENALT dbfileset, ratio

Examples: %DBGENALT @.DB, .50
          %DBGENALT @.DB (DBSETFULLNESS>.8 and MODDATE>TODAY-30), 0.6

The %DBGENALT command uses the DBGENERAL utility to change the capacity of
IMAGE datasets so that they are a given percentage full (this command will only
work if you own DBGENERAL, which is a product of BRADMARK Technologies, Inc.).

For instance, the command in the above example increases the capacity of all
databases in the DB group that are currently greater than 80% full so that they
are only 60% full.


_DBMGRALT_660
%DBMGRALT

Syntax:   %DBMGRALT dbfileset, ratio

Examples: %DBMGRALT @.DB, .50
          %DBMGRALT @.DB (DBSETFULLNESS>.8 and MODDATE>TODAY-30), 0.6

The %DBMGRALT command uses the DBMGR utility to change the capacity of IMAGE
datasets so that they are a given percentage full (this command will only work
if you own DBMGR, which is a product of Dynamic Information Systems
Corporation).

For instance, the command in the above example increases the capacity of all
databases in the DB group that are currently greater than 80% full so that they
are only 60% full.


_DEALLOCATE_661
%DEALLOCATE

Syntax:   %DEALLOCATE fileset

Examples: %DEALLOCATE @.@.@(ISCMPROG)

Deallocates program files.  Since only compatibility mode program files can be
allocated, use of the file attribute variable ISCMPROG as shown here will speed
up the execution of this command.

See %ALLOCATE for more details on allocating programs.

Syntax:   %DELETEALARM alarmnumber

Examples: %DELETEALARM

%DELETEALARM deletes the alarms you set via the %ALARM command.  For more
information, see the documentation on %ALARM.


_DELETESPOOLFILE_662
%DELETESPOOLFILE

Syntax:   %DELETESPOOLFILE spoolfileset

Examples: %DELETESPOOLFILE $STDLIST.@.@(SPOOL.OUTPRI<=2)
          %DELETESPOOLFILE @.@.DEV-RPT@.@.@(SPOOL.READYDATE<TODAY-2)
          %DELETESPOOLFILE $STDLIST.@.DEV(SPOOL.JSNAME MATCHES "COM@")

MPEX's %DELETESPOOLFILE command lets you:

   * Delete entire filesets of spool files at once;

   * Find the spool files to be deleted by their "vital attributes" (spool file
     name, creating job name, output priority, creation date, etc.);

   * Delete spool files if you

     - are console operator, or

     - have SM or OP capability, or

     - have AM capability and are deleting spool files in your own account, or

     - are the spool file's creator.

No more wading through SPOOK5 >SHOW command listings; no more having to >TEXT
each file individually to see what the names of their creating jobs are; no
more risk of a mistyped digit deleting the wrong spool file.  The command


Spool_files__deleting_by_output_priority_663
Spool files: deleting by output priority

   %DELETESPOOLFILE $STDLIST.@.@(SPOOL.OUTPRI<=2)

will delete all job $STDLISTs whose output priority is 2 or less;

   %DELETESPOOLFILE @.@.DEV-RPT@.@.@(SPOOL.READYDATE<TODAY-2)

will delete all DEV account spool files made ready more than 2 days ago except
for those whose spool file names begin with RPT;

   %DELETESPOOLFILE $STDLIST.@.DEV(SPOOL.JSNAME MATCHES "COMP@")

will delete all DEV account $STDLISTs created by jobs whose job names start
with COMP (presumably the listings of compile job streams).

MPE/iX Native Mode Spooler Note:


MPE_V_and_MPE_iX_differences__NM_spooler__DELETESPOOLFILE_664
MPE/V and MPE/iX differences: NM spooler %DELETESPOOLFILE

The Native Mode Spooler on MPE/iX does not retain the spoolfile's group name.
If you specify a group name in %DELETESPOOLFILE on MPE/iX, it will be
effectively ignored.  For example,

   %DELETESPOOLFILE $STDLIST.PUB.PROD

is the same as

%DELETESPOOLFILE $STDLIST.@.PROD

Syntax:   %DELETELVAR varset [ ,...  ]

Examples: %DELETELVAR COUNTER
          %DELETELVAR J, K, L
          %DELETELVAR K#, FOO@

The %DELETELVAR command deletes local variables.  Please see "Local Variables"
in the MPEX Variables chapter of this manual for more details.


_DELETEVAR_665
%DELETEVAR

Syntax:   %DELETEVAR varset [ ,...  ]

Examples: %DELETEVAR X1
          %DELETEVAR TEMPV@, MYFILENAME

%DELETEVAR deletes all the specified MPEX variables.  You may use wildcards (@,
#, or ?) to delete all the variables whose names match a given pattern.  For
more information on this command, see the MPEX Variables chapter.


_DEMO_666
%DEMO

Syntax:   %DEMO [section]

Examples: %DEMO
          %DEMO 3

This command starts the MPEX 'self-demo', which shows you some of the major
features of MPEX.  The demo consists of an introduction and 5 sections
(covering each of the 5 major areas where MPEX enhances your system).  You may
stop the demo at any time, and restart it later at the beginning of any
section.


_DEVCONTROL_MPEX_command__667
%DEVCONTROL MPEX command

Syntax:   %DEVCONTROL ldevnumber; LOAD|ONLINE

Examples: %DEVCONTROL 7;ONLINE


MPE_V_and_MPE_iX_differences___DEVCONTROL_command_668
MPE/V and MPE/iX differences: %DEVCONTROL command
   Note: This command is only available on MPE/iX systems, version 3.0 and
         later.

One of the few drawbacks of HP's DDS tape drives is that they have no "on-line"
button.  In order to put a tape back on-line, you must first eject the tape and
then re-insert it.

The %DEVCONTROL command uses the HPDEVCONTROL intrinsic to either load a
mounted tape, or put a loaded tape on-line.

Another use for this command: many of the new backup systems and devices have
the capability to do a full backup of some systems without an operator present
to mount additional tapes.  However, once the backup is complete, you have to
wait for an operator to put the tape back "online" in order to validate that
the files were successfully store to tape.

After your backup is done, you can use the %DEVCONTROL command to put the tape
back on-line, then verify your backup (using MPE/iX's :VSTORE command), all
without an operator present!

Syntax:   %DO  [abscmdnum      ]  [,editstring]
               [-relcmdnum     ]
               [cmdnum1/cmdnum2]
               [["][@]string["]]

Examples: %DO 155
          %DO -2
          %DO 155/158
          %DO RUN
          %DO @MYFILE

%DO re-executes a command that you typed earlier and that has been saved in the
MPEX command history.

%DO, %LISTREDO, and %REDO are all intimately related, and are discussed in full
detail under the %REDO command in this manual.

Syntax:   %DOSAVED ;FILE= savefile
          [;NOVERIFY]
          [;QUIET]
          [;MUSTEXEC]
          [;mpeschedparms]

Examples: %DOSAVED;FILE=SAVEDJBS
          %DOSAVED;FILE=PRODJOBS; NOVERIFY; AT=23:30
          %DOSAVED;FILE=ALLJOBS; QUIET; MUSTEXEC
          %DOSAVED;FILE=CRITJOBS; IN=0,0,5

%DOSAVED re-submits jobs that were saved via the %SAVEJOB command.  For more
information, see the documentation on %SAVEJOB.


_ECHO_669
%ECHO

Syntax:   %ECHO [message]

Examples: %ECHO PLEASE WAIT WHILE WE RUN AP000
          %ECHO
          %ECHO !PROCESSEDFILES files processed, !FAILEDFILES errors

The %ECHO command outputs the specified message to the terminal.  It's most
useful when you're executing a UDC or a command file and want to tell the user
something.

%ECHO is also useful for outputting the values of variables, since "!"s and
"![...]"s are processed before the message is output.  See the chapter on MPEX
Variables for more information.

If you want to output text with leading spaces, just insert the right number of
spaces (plus the one that always goes after the %ECHO) between the %ECHO and
the message.  %ECHO is the only command that actually cares how many spaces
there are between it and its parameters.


_EDIT_670
%EDIT

Syntax:   %EDIT fileset, editcommands

Example:  %EDIT @.SOURCE(CODE="EDTCT"), SET VARIABLE

The %EDIT command lets you perform an EDITOR/3000 command (or multiple commands
separated by semicolons) on an entire fileset:

   * To change all occurrences of one string to another in a fileset, say

        %EDIT @.SOURCE, CHANGE "ACCT-TYPE", "ACCOUNT-TYPE", ALL

     MPEX will tell EDITOR to /TEXT each file, do the /CHANGE, and then /KEEP
     it back (note that the /KEEP will happen regardless of whether or not the
     /CHANGE actually changed anything -- see the %EDITCHG command for a better
     solution).


Disc_space_671
Disc space
   * To convert your fixed record-length COBOL source files to variable
     record-length files (and save up to 30-50% of their disc space!), say

        %EDIT @.SOURCE(CODE="EDTCT"), SET VARIABLE

(Note that this works only for COBOL files or UNNUMBERED files; NUMBERED
     non-COBOL files will be rendered uncompilable by an EDITOR /SET VARIABLE
     command -- if you accidentally do this to them, just do another %EDIT
     command to do a /SET FIXED.)

WHEN WILL %EDIT "/KEEP" THE FILE?

Naturally, we didn't implement all the functions of EDITOR inside MPEX.  For
each file in the fileset, MPEX actually runs EDITOR and passes to it:

   * A /TEXT command to text in that file;

   * The command you specified (/LIST, /WHILE, /CHANGE, etc.);

   * Possibly a /KEEP command to keep the file back;

   * An /EXIT command to return control back to MPEX.

When does MPEX tell EDITOR to /KEEP a file? Well, if your EDITOR command
includes only those commands that MPEX knows will never change the file (e.g.
/LIST, /WHILE, /FIND, etc.), MPEX will not tell EDITOR to /KEEP the file.

If, however, there's any chance that the file may be changed by your command --
for instance, if your command is a /CHANGE, a /JOIN, a /SET, etc.  -- MPEX will
tell EDITOR to do the /KEEP, to prevent your changes from getting lost.

If you know that you don't want to do a /KEEP, you can just append ";EXIT" to
your command, e.g.

   %EDIT @.SOURCE, CHANGE "ITEM-NUM", "ITEM-NUM", ALL; EXIT

This will cause EDITOR to /EXIT before it gets a chance to do the /KEEP.

Actually, there's little harm in doing an unnecessary /KEEP; file parameters
(creator ID, creation date, modify date, etc.) will get changed, but the data
will remain intact.  Still, it's a good idea to avoid doing /KEEPs unless you
need to (if only for speed's sake) -- this is why MPEX automatically avoids
/KEEPs in certain cases and lets you explicitly avoid them yourself by
specifying a ";EXIT" at the end of your EDITOR command.


_EDITCHG_672
%EDITCHG

Syntax:   %EDITCHG fileset, "fromstring", "tostring" [,quotechar]

Examples: %EDITCHG @.SOURCE, "ACCT-TYPE", "ACCOUNT-TYPE"
          %EDITCHG @.SOURCE, "DD""MM'YY", "DD'MM'YY", \line
Saying

   %EDITCHG @.SOURCE, "ACCT-TYPE", "ACCOUNT-TYPE"

does exactly the same thing as saying

   %EDIT @.SOURCE, CHANGE "ACCT-TYPE", "ACCOUNT-TYPE", ALL

-- it changes all occurrences of "ACCT-TYPE" to "ACCOUNT-TYPE" in all SOURCE
group files.  However,

   * It will only /KEEP those files that are actually changed.

Any files that do not contain the string "ACCT-TYPE" are not /KEEPed back --
their creation and last modify dates aren't changed, and neither are any other
parameters (like file code, record type, etc.) that EDITOR is prone to
changing.

Thus, for doing EDITOR /CHANGEs, the %EDITCHG command is both more efficient
and more convenient -- for instance, since the last modify date of the files
that don't have "ACCT-TYPE" is not changed, those files won't be automatically
included on daily stores.

What if the string you want to change contains both single- and double-quote
characters? EDITOR allows you to use some character that doesn't occur anywhere
in the string as a string delimiter (e.g.  a "), but MPEX doesn't.  To tell
%EDITCHG to use a different quote character, include it as the third parameter;
the "fromstring" and "tostring" must still be enclosed in matching quotes
(either single ' or double ").  (To embed quotes in a quoted string within
MPEX, you simply type the quote character twice.)

For example, to change the string

   CODE'VAL:="A";

to:

   CODE'VAL:="B";

in the fileset "@.SOURCE", use the command

   %EDITCHG @.SOURCE, 'CODE''VAL:="A"', 'CODE''VAL:="B"', \line
(Notice that you do not use the " character in the "fromstring" or "tostring"
yourself; %EDITCHG does it for you.)


_EDITQUAD_673
%EDITQUAD

Syntax:   %EDITQUAD fileset, quadcommands

Examples: %EDITQUAD @.SOURCE, C "ACCT-TYPE", "ACCOUNT-TYPE"

(QUAD is a popular contributed text editor.) If you have QUAD set up as
QUAD.PUB.VESOFT, MPEX's %EDITQUAD command will execute a QUAD command (or
multiple commands separated by semicolons) on a fileset.

MPEX will, for each file in the fileset, run QUAD.PUB.VESOFT, tell it to /TEXT
in the file, execute the commands you gave, do a /KEEP, and do an /EXIT.

If you don't want QUAD to /KEEP the file, append an ";EXIT" to the quadcommand,
e.g.

   %EDITQUAD @.SOURCE, LIST ALL OFFLINE; EXIT

Otherwise, MPEX will always tell QUAD to /KEEP the file.

The "<" and ">" characters are special characters in MPEX (and MPE/iX)
indicating I/O re-direction (see Redirecting Command Input and Output in the
MPEX User Manual).  QUAD uses these characters to indicate a "Range File".  In
order to use them in an %EDITQUAD command, you must prefix them with two "!"
characters (not just one).  For example,

   %EDITQUAD WORK@, COPY !!<NEWSTUFF!!> TO 4


_EDITTDP_674
%EDITTDP

Syntax:   %EDITTDP fileset, tdpcommands

Examples: %EDITTDP @.SOURCE, FIND "ITEM-NUM"; EXIT
          %EDITTDP @.SOURCE, CHANGE "TO", "TWO", ALL

Just as the %EDIT command lets you execute an EDITOR command on a fileset, so
the %EDITTDP command lets you execute a TDP command (or several commands
separated by semicolons) on a fileset.

For each file in the fileset, MPEX tells TDP to:

   * /TEXT it,

   * execute the specified command (or commands),

   * /KEEP it, and

   * /EXIT.

If you want to just execute the command and not do a /KEEP (for instance, if
the command is a /LIST ALL,OFFLINE), you should append an ";EXIT" to your TDP
command:

   %EDITTDP fileset, LIST ALL,OFFLINE; EXIT

This will make TDP do the /EXIT before it gets a chance to do the /KEEP.  If
you don't specify the /EXIT, the /KEEP will always be executed (even for /LIST
commands).


_ERASE_675
%ERASE

Syntax:   %ERASE fileset

Examples: %ERASE @.DATA

The %ERASE command erases the contents of the files while leaving the file
structure intact (record size, ASCII/BINARY, blocking factor, etc.).  This is
similar to the %PURGE command; however, when you are done, the files will
continue to exist (they simply won't contain any data).


_ERRCLEAR_676
%ERRCLEAR

Syntax:   %ERRCLEAR

Sets the variables CIERROR, CIERRORISWARN, FSERROR, HPCIERR and HPFSERR to 0.


_ESCAPE_677
%ESCAPE


CIERR_678
CIERR

Syntax:   %ESCAPE [[CIERR=] errnum]

Examples: %ESCAPE
          %ESCAPE 985


_TRAPERROR_and__ESCAPE__679
%TRAPERROR and %ESCAPE
Terminates all levels of the currently executing UDC/command file/batch job
(unless there is a %CONTINUE or %TRAPERROR in effect), sets CIERROR to the
absolute value of errnum, and sets HPCIERR to the value of errnum.

   * If there is a :CONTINUE in effect, execution continues with the next
     command.

   * If there is a %TRAPERROR in effect, execution continues from the next
     %IFERROR or %CLEANUP.


_EXIT_680
%EXIT

Syntax:   %EXIT

Examples: %EXIT
          END OF PROGRAM

%EXIT will terminate the active MPEX process, unless it's being run from within
another program, in which case it will suspend MPEX instead of terminating it.
MPEX will not attempt to suspend when being run from within the command
interpreter.

If you need to terminate MPEX without attempting to suspend, use the %QUIT
command.  If you need to terminate both MPEX and the current Session, use the
%BYE command.


_END_681
%END


_E_682
%E
Two synonyms for %EXIT are also supported: both %E and %END have the same
effect as %EXIT.


_FCOPY_683
%FCOPY

Syntax:   %FCOPY [FROM=] fromfileset,[TO=] tofileset
          [;fcopyparms]

Examples: %FCOPY S@.SRC+P@.PUB, =.OLD; NEW
          %FCOPY FROM=RPT@.DATA; TO=SEL@.=; NEW; SUBSET="X7"

The %FCOPY command lets you copy filesets using FCOPY.  This is useful if you
want to use FCOPY's special features, like ;SUBSET=, ;CHAR=, etc.

Simply put, MPEX's %FCOPY runs FCOPY for each file in the fileset and tells it
do a copy FROM=fromfile;TO=tofile with the parameters you specified.

If the first parameter in the "fcopyparms" is "NEW", MPEX will automatically
purge the target file.  Other than that, typing this command is identical to
saying:

   %REPEAT
   %>:FCOPY FROM=!MPEXCURRENTFILE;TO=![OBJECTFILE('tofilemask')];fcopyparms
   %>FORFILES fileset

(see the %REPEAT ...  %FORFILES section for details on this command and the
OBJECTFILE(...) function).


_FILTER_684
%FILTER

Syntax:   %FILTER "command" [,searchexpression[;mpexprintparms]]

Examples: %FILTER "SHOWJOB", " 113 "
          %FILTER "RUN MYPROG", CL"TOTAL"
          %FILTER "%COBOLII @.SOURCE,=.PUB", "ERROR"; CONTEXT=-2
          %FILTER "SHOWDEV", "DOWN PENDING" OR "DP"

Have you ever done a SHOWJOB in order to find out who was logged on to a
particular LDEV, only to have to wade through screen after screen of data
searching for the LDEV number you were interested in? Or run a program that
produces a whole bunch of output, when all you're really interested in is the
"TOTAL" line?

The "%FILTER" command lets you execute any command that you could normally type
at MPEX's "%" prompt, and "filter" the output using the MPEX %PRINT command's
powerful "SEARCH=" facility.  (In fact, %FILTER is merely a convenient
combination of %PRINT, documented in this manual, and the STDLIST(...)
function, documented in Appendix; it has been implemented to make using these
features more convenient -- take a look at FILTER.CMD22.VESOFT!)

As you can see from the examples above, the first parameter is the command you
wish to execute.  If it needs to contain spaces, commas, or semi-colons, you
must put quotes around it.

The second parameter is the same kind of thing you can pass to the
FSEARCHEXP(..) function: a %PRINT;SEARCH= type of expression optionally
followed by any additional %PRINT parameters (like CONTEXT=, PREV=, etc.).

For example, to see all of the jobs on your system that are SCHED and have
HIPRI (which SHOWJOB displays as inpri 15), you could say:

   %FILTER "SHOWJOB SCHED", " 15 "

Note: since %FILTER simply executes the %PRINT command, it is affected by any
variables you may have set that would affect %PRINT (like MPEXPRINTNONDELIMS).
For more details on the search expression, see "%PRINT;SEARCH=" in the "MPEX
Commands" section of this manual.


_GOON_685
%GOON


Background_execution_of_MPEX_commands___GOON_686
Background execution of MPEX commands: %GOON

Syntax:   %GOON command

          %SHOWGOON

Examples: %GOON PRINT @.SOURCE;SEARCH="SOC-SEC-RATE";NUM
          %GOON ALTFILE @.@.DEV; XLTRIM; KEEPAMDATES
          %GOON COBOL MYPROG.SOURCE,=.PUB

%GOON (which stands for "go on") lets you execute any command that you could
normally type at the MPEX prompt as a son process, immediately returning
control of your terminal to you, and re-directing output of the command to a
session-temporary file! This lets you run tasks that may take a long time to
complete in the "background", without tying up your terminal.  It is similar to
the ;GOON keyword of MPEX's enhanced %RUN command (documented later in this
manual).

Here is an example of using %GOON:

   %GOON LISTF @.SOURCE.DEV(FSEARCHSTRING("PART-NUMBER")>0),2
   Output will be sent to temporary file VEOU139
   %

After typing %GOON LISTF...  and pressing [RETURN], you immediately get an MPEX
prompt again.  This allows you to do other things while this LISTF is executed
in the background.  The output of %GOON LISTF...  is redirected to a temporary
file named VEOU139 (in this example), so that it doesn't interfere with your
display while you are doing other things.  Sometime later, a message will
appear (over your function key labels if you have an HP terminal) that says:

   Execution of LISTF done; see file VEOU139

to see the results, simply %PRINT the output file.

   %PRINT VEOU139

As you can see, when you enter an MPEX command using %GOON, you will be told
the name of the temporary file that the output will be sent to.  When the
command is done, a message letting you know it is done will be sent to your
terminal (written over your function key labels, if you have an HP terminal,
the same way the %WARNF command does), telling you which command finished (in
case you have more than one %GOON running!) and reminding you of the name of
the output file for that command.

If you were to %EXIT from MPEX before one of your %GOON processes completed, it
would be automatically killed.  To prevent this from happening, MPEX will not
let you exit; if you try to, you'll get the message:

Error: Son processes still running, you must %KILL them before exiting.

Simply use the %SHOWGOON command (described below) to see which ones are still
active, and wait for them to finish or %KILL them.

What advantage does the %GOON command have over MPEX's $command, %SUBMIT...  ,
and %SCHEDULE...  , all of which create a job stream to execute the command for
you?

   * Job streams frequently have to sit in the WAIT queue for a while before
     actually logging on;

   * after WAITing, the job has to log on, which is a high-overhead operation;

   * many users launching background tasks may clutter up your job queue and
     create a lot of $STDLIST spoolfiles;

   * finally, since the %GOON command executes within your session, it has
     access to all of your MPEX (or MPE/iX) variables and TEMP files.

CHECKING STATUS OF %GOON PROCESSES (%SHOWGOON)


_SHOWGOON_687
%SHOWGOON
To check the status of all of your %GOON processes type %SHOWGOON, e.g.

   FILENAME  [STATUS]  COMMAND

   VEOU53    [done]    PRINT @.SOURCE;SEARCH="SOC-SEC-RATE";NUM
   VEOU73    [active]  ALTFILE @.@.DEV; XLTRIM; KEEPAMDATES
   VEOU94    [active]  COBOL MYPROG.SOURCE,=.PUB

In this example the %ALTFILE and %COBOL commands are still running, but the
%PRINT is done.

SETTING %GOON PROCESSES' PRIORITY


VESOFTGOONPRI_688
VESOFTGOONPRI

By default, %GOON commands are executed in the DS queue, in order to minimize
their impact on your system.  On most systems, this gives them the same
priority as normal batch jobs.

You can change which queue your %GOON processes execute in by setting the
variable VESOFTGOONPRI to "CS", "DS", or "ES"; e.g.  to have all future %GOON
processes that you create (in the current session) execute in the CS queue,
simply type

   %SETVAR VESOFTGOONPRI "CS"

The maximum value that you can actually run %GOON processes at may be limited
by the system manager by using the %SET GOONMAXPRI command (documented later in
this manual).


_HELP_689
%HELP


_SEC_HELP_690
%SEC HELP


_VEAUDIT_HELP_691
%VEAUDIT HELP


_HELP_for_normal__MPE_commands__692
%HELP for normal :MPE commands

Syntax:   %HELP [keyword]                help on MPEX
          %SEC HELP [keyword]            help on SECURITY
          %VEAUDIT HELP [keyword]        help on VEAUDIT
          %HELP :[keyword]               help on MPE                    (NEW)
          %HELP CIERR number             Displays CI error messages     (NEW)
          %HELP FSERR number             Displays FILE SYSTEM messages  (NEW)
          %HELP LOADERR number           Displays LOADER error messages (NEW)
          %HELP POSIX                                      (POSIX)

Examples: %HELP INTRODUCTION
          %SEC HELP INTRODUCTION
          %VEAUDIT HELP INTRODUCTION

             gets you a general introductory discussion of MPEX, SECURITY, or
             VEAUDIT.

          %HELP NEWS
          %SEC HELP NEWS
          %VEAUDIT HELP NEWS

             gets you help on new features of the current version of MPEX,
             SECURITY, or VEAUDIT.

          %HELP :SHOWCATALOG

             opens the MPE help file, CICAT.PUB.SYS, and displays the normal
             MPE help on this command or keyword.  Since this uses MPEX's help
             facility, it means that MPE's help can finally be back-scrolled!


_HELP_693
%HELP
See also: %SYNTAX, %SEC SYNTAX, %VEAUDIT SYNTAX

The %HELP command lets you read this manual (and its index!) online.

MPEX's %HELP facility is conceptually oriented.  What this means to you is that
the %HELP command allows you to ask for help on general concepts, rather than
on a specific command.  There are very many -- literally thousands -- of
keywords you can get help on.

As an example, someone familiar with DOS on a PC would know that the DEL
command is used to DELETE files from the disk.  Typing DEL in MPE or MPEX,
however, returns UNKNOWN COMMAND NAME.  In MPEX, you could type:

   %HELP DELETE

MPEX will respond with something like:

   Help is available on:
     1.  %PURGE: Deletes a file or fileset
     2.  VEMODIFY: Control-D (Delete character)
     3.  Spool files: deleting by output priority
     4.  %DELETELVAR, MPEX command
     5.  %DELETEALARM, MPEX command
     6.  %DELETESPOOLFILE, MPEX command
     7.  MPE/V and MPE/iX differences: NM spooler %DELETESPOOLFILE
     8.  MPE's :DELETESPOOLFILE help text
     9.  %DELETEVAR, MPEX command
    10.  MPE's :DELETEVAR help text
   Which of the above would you like help on?

You realize that the thing you want is probably item #1 ("PURGE: Deletes a file
or fileset"), so you enter "1".  MPEX will now display for you the manual page
that contains the description of the %PURGE command.  MPEX will then prompt
you:

(F)orward,(B)ack,(>)forward 1/2 page,(<)back 1/2 page,(M)enu,(E)xit?

This lets you page forward and backward through the manual to read the entire
%PURGE section of the manual (which could be several pages).

Note that when MPEX shows you the manual page describing the thing you asked
for, the actual description will start about a third of the way down the
screen; thus, it displays about eight lines of manual text that comes before
the description as well as the description itself.

This is done because the text that immediately precedes the description is
often (though not always) related information that might be useful to you as
well.  As long as you remember that the thing you asked for actually starts at
about line eight or nine of the screen, you shouldn't get confused.

When you're done reading the manual, type "E" to get back to the % prompt or
"M" to get back to the DELETE keyword menu we showed above (in case you realize
you chose the wrong option).

This online HELP index is even more useful than the index in the back of this
manual, since the %HELP command finds all the index entries that contain the
given keyword (not just those that start with that keyword).

You don't need to specify the full keyword; you might, for instance, say:

   %HELP CRE

which will get you a menu like:

   Help is available on:
     1.  Spool files: selecting by creating job/session name
     2.  CREDATE, file attribute variable
     3.  CRETIME, file attribute variable
     4.  CREATOR, %ALTFILE command keyword
     5.  CREATOR, file attribute variable
     6.  Security: removing creator-only restrictions

As you see, index entries containing the strings "creating", "CREDATE", and
"CRETIME" -- any string that starts with "CRE" -- were found.

In addition to the MPEX commands, the help facility will also access the MPE
help catalog keywords and topics (see the %HELPMAKE command for details).
These are noted in the menu as "MPE's :COMMAND help text" where COMMAND refers
to an MPE command that matches the keyword that you entered.  In the first
example, for %HELP DELETE, the MPE commands :DELETESPOOLFILE and :DELETEVAR
were listed as well.  You can select either of these by number, just as any
other MPEX command, and move forward and backward through MPE's help text on
these commands.

GETTING HELP ON SECURITY AND VEAUDIT TOPICS


_SEC_HELP_694
%SEC HELP


_VEAUDIT_HELP_695
%VEAUDIT HELP

When you request help on a topic, MPEX normally searches the MPEX manual first.
If the topic you are interested in is in the MPEX manual, then the %HELP
command displays the topic and does not search any farther.  If the topic you
requested is not in the MPEX manual, then the SECURITY and is searched, and if
not there, then the VEAUDIT manual, and finally, the MPE CI or UDC help.
Normally, this is exactly what you want; however, there are a number of
SECURITY and VEAUDIT topics that are mentioned in this manual, so it is
possible that requesting help for what is primarily a SECURITY topic would
result in a listing of only those topics explained in the MPEX manual.

In order to force the %HELP system to search the other manuals, preface the
command with %SEC (for SECURITY topics) or %VEAUDIT (for auditing related
topics).

GETTING HELP ON MPE CI, FILE, AND LOADER ERRORS

On CLASSIC systems, HP supplies a utility called EXPLAIN that explains what a
particular CIERROR number means.  On MPE/iX systems, the text of each CIERROR
is included as part of the CICAT.PUB.SYS file.  Our %HELP command can make use
of this information to display the "help text" for any given CIERROR.  When you
type

   %HELP CIERR 976

MPEX will display the text associated with the error, including any suggestions
for recovering from the error now and avoiding the error in the future.
Similarly, help for LOADER errors can be found with:

   %HELP LOADERR 36

and FILE SYSTEM (FS) errors with:

   %HELP FSERR 100

You can also get help on the following special keywords:

   INTRODUCTION         an introductory discussion of MPEX in general
   CONTENTS             on-line access to the Table Of Contents
   FILESETS             information on MPEX filesets
   NEWS                 new features of MPEX
   :SUMMARY             summarizes MPE HELP system commands/topics

Finally, if you just say

   %HELP

MPEX will display this very chapter.

Note that MPEX's %HELP is used primarily for getting help on MPEX, SECURITY,
and VEAUDIT features from these manuals as well as displaying the MPE help
catalog (CICAT.PUB.SYS) with the ability to scroll forward or backward at will.
If you want help on  UDCs or command files (which are not contained in
CICAT.PUB.SYS) then you must preface the HELP command with a ":" as follows:

   %:HELP MPEXMGR


_HELPMAKE_696
%HELPMAKE

Syntax:   %HELPMAKE [;NOMPE]

Examples: %HELPMAKE

The %HELPMAKE command rebuilds and re-indexes our internal help files.  By
default, the current MPE help catalog (CICAT.PUB.SYS) is indexed as well.  This
is done automatically when installing or updating our software and when we
detect that you have updated the operating system.  Although at MPE update time
HP's installation job does not know that you have our software, (and therefore
does not execute this command), our program can detect that the MPE help
catalog has been updated later than our help catalog and therefore needs to be
indexed.  We only do this the first time you issue a %HELP command in MPEX and
the files are 'out of sync'.


_HOOK_697
%HOOK

Syntax:   %HOOK filename
          [;MPEXPREFIX= char]

Examples: %HOOK DBUTIL.PUB.SYS

This command allows you to "HOOK" programs, so that you can execute MPEX
commands from within them! Please see the MPEX HOOK chapter elsewhere in this
manual for more details.


MPEXPREFIX__698
MPEXPREFIX=
In the rare cases where the "%" character is needed to begin a line in your
application, you can specify an alternate "trigger" character to invoke MPEX.
Simply add

     ;MPEXPREFIX="x"

to the %HOOK command.  "x" can be any special character and will default to
"%".  When you begin a line of input in your application with this character,
the HOOK procedure will intercept the line and execute it as an MPEX command.


_IDENTIFY_699
%IDENTIFY


_DELETE_700
;DELETE


_NOCHECK_701
;NOCHECK


_SYS_702
;SYS

Syntax:   %IDENTIFY filereference, "description"
          [;NOCHECK]
          [;SYS]

          %IDENTIFY filereference ;DELETE
          [;NOCHECK]
          [;SYS]

Examples: %IDENTIFY MYSOURCE, "My latest program (source code)"
          %IDENTIFY MYSOURCE ;DELETE
          %IDENTIFY EDITOR.PUB.SYS, "System editor";SYS

This command allows you to apply an extended description to a file.  We store
the extended description in a file called ID.DATA.VESOFT.  The extended
description will be shown when you use %LISTF fileset,ID (see the %LISTF
section for details).  Although each description may be up to 80 characters in
length, you may find it convenient to limit your descriptions to 31 characters
to avoid line wrapping when using %LISTF ,ID.

The file specified by filename must exist on the system to be identified or
deleted; however, the ;NOCHECK keyword will allow you to override this
requirement.  Use the ;DELETE option to remove an extended description from the
file.  NOTE: This does not :PURGE the file, it merely removes the extended
description from our data file.

For your convenience, we have pre-loaded the data file with descriptions of all
the files found in the VESOFT and VECSL accounts along with the files found in
the PUB and HPBIN groups of the SYS account.  If you wish to change these
descriptions, or have additional files in these groups that we have not
identified, then you must use the ;SYS keyword.

SECURITY CONSIDERATIONS


_IDENTIFY_SECURITY_CONSIDERATIONS_703
%IDENTIFY:SECURITY CONSIDERATIONS

In order to set or change an identification string for a file, you MUST be
either the file's creator, the account manager of the account where the file
resides, or a system manager.  You must have SM capability to use the ;SYS
keyword for predefined files.


_IF_704
%IF


_ELSEIF_705
%ELSEIF


_ELSE_706
%ELSE


_ENDIF_707
%ENDIF

Syntax:   %IF logicalexpression [THEN]
          %   [command]
          %   [ ...  ]
          %[ ELSEIF logicalexpression [THEN]
          %   [command]
          %   [ ...  ]
          %[ ELSE
          %   [command]
          %   [ ...  ]]]
          %ENDIF

Examples: %COMMENT --- Check room in dataset 1
          %IF VEFINFO("DBASE01").DBSETFULLNESS > .90 THEN
          %    ECHO ERROR: The dataset is more than 90% full!!!
          %    ECHO        Aborting...
          %    RETURN
          %ELSEIF VEFINFO("DBASE01").DBSETFULLNESS > .75 THEN
          %    ECHO Warning: the dataset is more than 75% full.
          %    INPUT ANSWER; PROMPT="OK to continue? "
          %    IF UPS(ANSWER[0:1])<>"Y" THEN
          %       RETURN
          %    ENDIF
          %ELSE
          %    ECHO No problem!  You have plenty of room...
          %ENDIF
          %COMMENT --- Continuing with the update

MPEX's %IF and %ELSEIF commands are just like MPE's :IF and MPE/iX's :ELSEIF
commands, but with one major enhancement: they give you the full power of
VESOFT expressions! (VESOFT expressions are constructed from the hundreds of
integer, boolean, string, real, date, and time variables, operators, and
functions documented in the Appendix.) The number of things you can do with
VESOFT expressions is practically unlimited; here are just a (very) few
examples to get you started:

   %IF NOT FEXISTS("DATAFILE") THEN
   %   ECHO The DATAFILE is missing!
   ...

%IF DATEDAY(TODAY+1)=1 THEN
   %   ECHO Today is the last day of the month.
   ...

%IF VEFINFO("DBROOT").OPENED THEN
   %   ECHO The database root file is opened; someone is
   %   ECHO currently accessing the database.
   ...

%IF UPS(PRINTOPREPLY("OK to start Payroll?")[0:1])="Y" THEN
   %   ECHO The console operator has confirmed;
   %   ECHO start the Payroll run now.
   ...


_INITUDCS_708
%INITUDCS

Syntax:   %INITUDCS [NOBUF]

Examples: %INITUDCS

The %INITUDCS command recognizes what UDCs you have :SETCATALOGed and makes
them accessible from within MPEX.

This is usually automatically done whenever you enter MPEX (because the
MPEXMGR.PUB.VESOFT file, which is always executed when you enter MPEX, by
default contains a %INITUDCS command).  However, if you press [BREAK] and do a
:SETCATALOG to change your effective UDCs, MPEX won't know about this change.
Entering

   %INITUDCS

will "refresh" MPEX's knowledge of which UDCs are in effect.  Thus, a typical
use would be:

   % [you press the [BREAK] key]
   :SETCATALOG NEWUDC
   :RESUME
   %INITUDCS

If you say

   %INITUDCS NOBUF

MPEX will read the UDC files MR NOBUF, which could be quite a bit faster than a
normal "%INITUDCS".

However, whenever MPEX needs to execute a UDC, MPEX will have to use more stack
space, possibly causing STACK OVERFLOW aborts.  If you really want to decrease
the time it takes to get into MPEX, you might want to replace the %INITUDCS in
MPEXMGR.PUB.VESOFT by a "%INITUDCS NOBUF" (see "Specifying Commands To Be
Executed Every Time MPEX Is Entered" in the Running MPEX section).  Then, if
you start getting STACK OVERFLOWs, you'll have to change back to "%INITUDCS".


_INPUT_709
%INPUT

Syntax:   %INPUT [NAME=] varname
          [;PROMPT= "prompt"]
          [;WAIT= waitseconds]

Examples: %INPUT MYFILE;PROMPT="Which file do you want to process? "
          %INPUT DUMMYVAR;PROMPT="Hit return to continue...";WAIT=3

As we discuss in the MPEX Variables chapter, MPEX variables can contain
arbitrary data that can be set with the %INPUT and %SETVAR commands and later
substituted into MPEX commands.

The %INPUT command prompts the user for input and stores it (as a string) in
the variable with the specified name.  For instance,

   %INPUT MYFILE;PROMPT="Which file do you want to process? "

will ask the user "Which file do you want to process? " and put the input into
the variable MYFILE.  (If the ;PROMPT= string hadn't been specified, the user
would be asked for input, but wouldn't be shown a prompt string.)

If the variable doesn't exist, it's created; if it exists, its old value is
thrown away and it's set to the user-input value.

If the user presses [RETURN], the old value of the variable is unchanged
(although if the variable didn't already exist, it is created and set to "").

If you specify ;WAIT=, MPEX will wait for at most "waitseconds" seconds for
user input; if the user doesn't respond by that time, the read will terminate
and the CIERROR JCW will be set to 9003.  In the example

   %INPUT DUMMYVAR;PROMPT="Hit [RETURN] to continue...";WAIT=3

we're not so much prompting for data as just waiting for the user to press the
[RETURN] key
 -- in this case, we should probably say:

   %NOMSG INPUT DUMMYVAR;PROMPT="Hit [RETURN] to continue...";WAIT=3

The %NOMSG prefix tells MPEX not to print an error message if an error occurs
-- this will prevent the error message "THE INPUT TIMED READ HAS EXPIRED.
(CIWARN 9003)" from being printed.


_KILL_710
%KILL

Syntax:   %KILL sonprocessname|sonprocesspin

Examples: %KILL SPOOK5.PUB.SYS
          %KILL 54

MPEX is a powerful process-handling environment (see "MPEX Process Handling" in
the MPEX Special Topics section of this manual) in which you can manage
multiple son processes, active or suspended.  For instance, if you say

   %SPOOK5

and then >EXIT out of it, SPOOK5 will remain suspended as a son process of
MPEX.  Then, when you type

   %SPOOK5

again (assuming you haven't exited MPEX in between the two %RUNs), SPOOK5 will
be re-activated rather than re-run from scratch -- a much faster and more
resource-efficient operation.  (Not all programs behave this way; SPOOK5 does,
MPEX itself does, and so do some others.)

Sometimes, you may find that you need to terminate a son process that's
suspended (or active -- see discussion of the %RUN ;GOON command).

For instance, if you get into SPOOK5, >TEXT in a spool file, and >EXIT back to
MPEX, the spool file will stay locked until you re-enter SPOOK5 and unlock it
(by doing another >TEXT) or until the SPOOK5 son process terminates (perhaps by
doing a >QUIT).  At this point, you may say

   %KILL SPOOK5.PUB.SYS

MPEX will look at all its son processes (only in your own session, of course,
and only MPEX's immediate sons) and kill the one that's running SPOOK5.PUB.SYS.
Alternatively, you might do a

   %SHOWTREE

to find out SPOOK5's PIN (Process Identification Number) and then kill it by
specifying the PIN:

   %KILL 54

(assuming that 54 is the appropriate PIN).

One more reason why you might want to %KILL a son process is if you want to
re-run that program with a different run-time parameter (e.g.  a different
;PARM=, ;INFO=, or entry point).  In this case, you certainly don't want the
process to be reactivated; you want to %KILL it and then do the %RUN with the
new parameters, which will create a new son process with the parameters
specified.


_LISTF_711
%LISTF

Syntax:   %LISTF fileset [:SPOOL|TEMP] ,mode [;listfile]
          [;NOTOTALS|NORMTOTALS|ALLTOTALS]
          [;NOPAGEHEAD]
          [;NOEXPANDDIR]                                   (POSIX)

Examples: %LISTF @.DEV-TEST@-@KEY, 0
          %LISTF @.@(CODE="EDTCT"), 1
          %LISTF @.@(SECTORS>10000 and NOT ISPRIV), 2
          %LISTF @.@.@(ACCDATE<TODAY-120 and NOT ISPRIV),3; *LP
          %LISTF @.DATA(ONDEVICE(2)), 4
          %LISTF @.UTIL.SYS(ISPROG and PROG.PMCAP), 5
          %LISTF MAIN000.DATA, ACCESS
          %LISTF @.DB.@(DBSETFULLNESS>.70 and DBSETTYPE<>"D"), DB
          %LISTF @.DATA, DISCUSE
          %LISTF @.DATA, SEC
          %LISTF MYFILE, XL3
          %LISTF @:SPOOL, 2
          %LISTF @.@.@:TEMP, 3

MPEX's %LISTF command is a vastly extended version of MPE's :LISTF command:

   * Naturally, not just MPE filesets but MPEX FILESETS (see some of the
     examples above) can be %LISTFed;

   * Many useful new modes (3, 4, 5, DB, XL3, and more) have been implemented.
     These modes can show you information that you never even dreamed of
     getting with MPE :LISTF.

   * Several synonyms are available for the numeric modes.  For instance,
     instead of having to remember to use -2 to show information on ACDs,
     simply use %LISTF MYFILE,ACD instead.

   * Tempfilesets and spoolfilesets can also be %LISTFed, using many of these
     modes, by simply appending :TEMP or :SPOOL to the fileset.

   * On POSIX systems, %LISTF will default to listing files from your Current
     Working Directory (CWD), which may not be an MPE GROUP if you have issued
     a :CHDIR command.


_NOEXPANDDIR_712
;NOEXPANDDIR
   * Also on POSIX systems, %LISTF will list, where appropriate, files found in
     subdirectories of the group or directory specified.  This behavior can be
     turned off by using the keyword ;NOEXPANDDIR.

By default, some %LISTF modes output no file/sector totals, while others output
file/sector totals only for those groups which have more than one file shown,
for those accounts which have more than one group shown, and grand totals only
if more than one account is shown.  All %LISTF modes (except for mode 6) by
default print page headers at the top of each page of output.

There are four keywords that you can put on a %LISTF that can alter these
defaults:


NOTOTALS_713
NOTOTALS
   * ;NOTOTALS -- don't output any file/sector totals.


NORMTOTALS_714
NORMTOTALS
   * ;NORMTOTALS -- output file/sector totals only for groups with more than
     one file, for accounts with more than one group, and grand totals only if
     more than one account.


ALLTOTALS_715
ALLTOTALS
   * ;ALLTOTALS -- output file/sector totals and grand totals for all groups
     and accounts, even if there is only one file in the group, one group in
     the account, or one account.


NOPAGEHEAD_716
NOPAGEHEAD
   * ;NOPAGEHEAD -- do not output page headers.


VESOFTPAGESIZE_717
VESOFTPAGESIZE
All %LISTF modes do a page break every 60 lines.  To change the page size, type

   :SETJCW VESOFTPAGESIZE=numlinesperpage


Displaying_the_system_name_in__LISTF_headings__718
Displaying the system name in %LISTF headings
If you have more than one HP3000 and would like to have your system name show
in the %LISTF headings, simply do a

   %SETVAR HPSYSNAME "yoursystemname"

(e.g.  "%SETVAR HPSYSNAME "ALPHA") before doing the %LISTF.  Even better, add
the SETVAR to your MPEXMGR.PUB.VESOFT file and the system name will always show
on all %LISTFs.

Note: HPSYSNAME is also used by SECURITY for the reports generated by LISTLOG
and LISTUSERS.


VESOFTSORTFILESIZE_719
VESOFTSORTFILESIZE
One final note on using %LISTF: if the number of files to be listed is very
large (more than 10000), you may get an error message regarding the file
SORTWRIT.PUB.VESOFT.  If this occurs, you can set the variable
VESOFTSORTFILESIZE to the number of files you expect to be listed.

   %SETVAR VESOFTSORTFILESIZE 100000
   %LISTF @.@.@,DATESORT.LISTF.VECSL

%LISTF MODES


_LISTF_MODES_720
%LISTF MODES

There are several different formats, or "modes", that %LISTF supports.  Here is
a brief listing of each mode, showing the symbolic name and mode number (when
available).  Several of these mode names correspond to the symbolic names that
MPE's :LISTFILE command supports.

Number     Name        Description
  -3                   HP's mode -3: file label as readable text &
LOCKWORD/CREATOR.
  -2       ACD         HP's -2 mode: shows ACD information.
  -1       LABEL       HP's mode -1: shows file label in octal (MPE/V) or hex
(MPE/iX)
   0       FILES       Default %LISTF mode: filenames only.
   1       SUMMARY     HP's mode 1; limited file information (TYPe, EOF,
FLIMIT).
   2       DISK        mode 1 information + disk space usage + file's age.
           XL3         HP's mode 3; file label as readable text.
           DETAIL      HP's mode 3, see XL3 for details.
   3                   MPEX's mode 3; shows last access/modify/creation &
restore dates.
           XL4         HP's mode 4: shows security related information.
           SECURITY    (same as above)
   4                   MPEX's mode 4: shows file location (full extent map).
   5                   MPEX's mode 5: shows program information (PREP parms,
CAPs).
   6       FILENAME    HP's mode 6: fully qualified filenames.
           QUALIFY     (same as above).
           ACCESS      Displays users accessing a file or fileset.
           DATES       Displays access, modify, create, restore, and state
change dates
           DB          Shows DATABASE statistics.
           DISCUSE     Shows drive-by-drive allocation of a fileset.
           ID          Helps identify the type & contents of a file
           SAVABLE     Displays space savable using ;XLTRIM or ;SQUEEZE for
each file.
           SEC         Shows actual file security considering group & account
access.


_LISTF_mode__0__FILES__721
%LISTF mode: 0 [FILES]

Syntax:   %LISTF fileset [,0]

Examples: %LISTF @.DEV-TEST@-@KEY(CODE="EDTCT"), 0

ACCOUNT=  VESOFT      GROUP=  DEV

AP000S      AP000U      AP010S*     AP100P      AP100S      BADRECS*
COMP000     COMP999     ...

As you see, MPEX's %LISTF mode 0 is quite similar to MPE's :LISTF mode 0, but
with a few distinct improvements:

   * Of course, the full power of MPEX filesets -- with "+"s, "-"s, and
     selection criteria -- is supported.  This lets you select files in ways
     that you never could before.

   * Account and group names are printed -- if you type a command such as

       %LISTF @CLOCK@.@.@

     you'll get group and account headers for each group in which a file is
     found (unlike MPE's :LISTF ,0).

   * Files that are in use are marked with an "*" (we thought that since we had
     the space on the listing, we might as well use it).


_LISTF_mode__1__SUMMARY__722
%LISTF mode: 1 [SUMMARY]

Syntax:   %LISTF fileset,1 [;listfile]
                           [;NOTOTALS|NORMTOTALS|ALLTOTALS]
                           [;NOPAGEHEAD]

Examples: %LISTF @.DEV-TEST@-@KEY(CODE="EDTCT"), 1

ACCOUNT=  VESOFT      GROUP=  DEV

FILENAME  CODE  ------------LOGICAL RECORD--------
                  SIZE  TYP        EOF      LIMIT

BEXP      EDTCT   256W  FB         633        958
...

ACCOUNT  TOTAL:   192 FILES                 35722 SECTORS

MPEX's %LISTF mode 1 is just like MPE's :LISTF ,1 except that:

   * It has the full power of MPEX filesets -- + filesets, - filesets,
     selection (by code, by disc space, by record size, etc.).

   * File counts and disc space totals (group, account, and grand) are printed.


_LISTF_mode__2__DISC__723
%LISTF mode: 2 [DISC]

Syntax:   %LISTF fileset,2 [;listfile]
                           [;NOTOTALS|NORMTOTALS|ALLTOTALS]
                           [;NOPAGEHEAD]

Examples:
%LISTF @.@(SECTORS>10000 and NOT ISPRIV),2

ACCOUNT=  LIST     GROUP=  VESOFT

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

CUST01  *      2560W  FB    566   566   1    11340 32 32   1    1
                    current 540     2 readers, 2 writers
...

ACCOUNT  TOTAL:    15 FILES                 231007 SECTORS

(POSIX)
%LISTF ./A@/,2

PATH= /DOC/WORK/

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

A01      KSAM   128W  FB      0  1023   1      128  1  *  20   20
A01K     KSAMK  128W  FB    210   210   1      224  2  8  20   20
A09     /       ==>  NEWFILE
A16              link /DOC/WORK/A09/NEWFILE     16  1  *
ACORELFT         80B  FA    135   135  16       48  1  1 119  145
...

DIRECTORY TOTAL:    17 FILES                 16432 SECTORS

PATH= /DOC/WORK/A09/

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

NEWFILE         128W  FB      0  1023   1        0  0  *  20   20

MPEX's %LISTF mode 2 is just like MPE's :LISTF ,2 except that:

   * It has the full power of MPEX filesets -- + filesets, - filesets,
     selection (by code, by disc space, by record size, etc.).

   * File counts and disc space totals (group, account, and grand) are printed.

   * The AGE of the file, both in terms of last access and last modification,
     are shown.

   * If the file is in use, the number of readers, the number of writers, and
     the actual EOF (if it's different from the one kept on disc) are also
     output.

     Note that on MPE/iX systems, native mode KSAM files (KSAMXL) will almost
     always report an EOF that is greater than the FLIMIT.  This is due to the
     fact that a KSAMXL file contains both the DATA and the KEY information in
     the same file.  The FLIMIT reported by :LISTF is the maximum number of
     DATA records, the CURRENT EOF reported by %LISTF shows the number of both
     KEY and DATA records combined.

   * On systems supporting POSIX, the contents of directories are shown as well
     as the destination of any LINK files.


_LISTF_mode__3__724
%LISTF mode: 3


Creator_ID__listing_725
Creator ID: listing


Creation_date__listing_726
Creation date: listing


Access_date__listing_727
Access date: listing


Modification_date__listing_728
Modification date: listing


Restore_date__listing_729
Restore date: listing


Modification_time__listing_730
Modification time: listing

Syntax:   %LISTF fileset,3 [;listfile]
                           [;NOTOTALS|NORMTOTALS|ALLTOTALS]
                           [;NOPAGEHEAD]

Examples: %LISTF @.@.@(ACCDATE<TODAY-120 and NOT ISPRIV),3

ACCOUNT=  TECH        GROUP=  MICHAEL

FILENAME CODE CREATOR CRE-DATE  MOD-DATE  MOD-TIME  ACC-DATE  RST-DATE

ADDTECHJ      MICHAEL 31 DEC 90 02 OCT 91 10:05 AM 02 OCT 91 13 DEC 91
AL            MICHAEL 06 MAR 91 02 OCT 91 10:05 AM 28 OCT 91 13 DEC 91
ALTREPRT      MICHAEL 02 AUG 91 12 DEC 91 04:58 PM 12 DEC 91 13 DEC 91
ASPLASH       MANAGER 24 OCT 91 12 DEC 91 04:58 PM 12 DEC 91 13 DEC 91
...

GROUP    TOTAL:    41 FILES                              52344 SECTORS

As you see, %LISTF mode 3 can get you information that you just can't get
otherwise in any sort of compact format:

   * The creator id of the file.

   * The creation date of the file.

   * The date the file was last modified.

   * The TIME the file was last modified (not shown in the above example
     because it wouldn't fit in the manual page).

   * The date the file was last accessed.

   * The date the file was last restored -- this is usually equal to the
     creation date unless you did a :RESTORE ;OLDDATE of this file, in which
     case it is the date of the restore.

These features are particularly useful when used together with the ACCDATE,
CREATOR, MODDATE, CREDATE, or RSTDATE selection criteria (note how everything
that can be shown using MPEX's %LISTF can be selected by as well!).  For
instance,

    %LISTF @.DATA(CREATOR<>"DBA"),3

will show you the creator IDs of all the files in the DATA group that weren't
created by the user DBA.  If you want to get REALLY fancy, you can say:

   %LISTF @.@.@(NOT USEREXISTS(CREATOR+"."+ACCOUNT)),3

This will find all the files in the system whose creators don't exist.  How
does it do this? See ";CREATOR=" in the %ALTFILE for a discussion -- it's too
long to repeat here.

Another interesting use for last access date selection criteria is security --
which files were accessed over the weekend? If you come in on Monday, you can
say

   %LISTF @.@.@(ACCDATE=TODAY-1 or ACCDATE=TODAY-2),3

This will find all the files accessed on Sunday (TODAY-1) or Saturday
(TODAY-2).  The mode 3 listing will tell you which day the access was on, and
also whether the file was also modified on that day.


_LISTF_mode__4__731
%LISTF mode: 4


Disc_space__listing_various_information_732
Disc space: listing various information


Device_class__listing_733
Device class: listing


Extent_map__listing_734
Extent map: listing

Syntax:   %LISTF fileset,4 [;listfile]
                           [;NOTOTALS|NORMTOTALS|ALLTOTALS]
                           [;NOPAGEHEAD]

Examples: %LISTF @.DATA(ONDEVICE(2)), 4

ACCOUNT=  VESOFT      GROUP=  DATA

-----FILE------ EXTENTS -BLKFACT- -----SECTORS-----  DEVICE      LABEL
NAME      CODE  NUM MAX  NOW BEST USED NOW  SAVABLE  CLASS       LDEV

MYFILE            4  32    1    3      136       28  DISC        2
   Dev/Sector:    1/%0000512114    2/%0000227353    1/%0000512156
   Dev/Sector:    3/%0000725756
MYDATA            7  32    1           238        8  DISC
   Dev/Sector:    3/%0000321710    2/%0000231143    2/%0000255345
   Dev/Sector:    1/%0000512220    2/%0000263320    3/%0000535323
   Dev/Sector:    1/%0000216607
   ...

GRAND  TOTAL:     37 FILES                115227 SECTORS

%LISTF mode 4 shows you information on the disc space used by a file.  In
particular, it shows certain things that :LISTF mode 2 doesn't:

   * The device class on which the file resides (i.e.  the ;DEV= parameter with
     which the file was built).

   * The best blocking factor for the file -- the blocking factor that would
     best optimize the file's disc space.  (This is not shown on MPE/iX systems
     because the blocking factor is irrelevant to MPE/iX disc space usage.)

   * The total amount of savable disc space -- the amount of space you'd save
     if you %ALTFILEd this file with ;BLKFACT=BEST;SQUEEZE (improving the
     blocking factor and setting its FLIMIT to its EOF).

   * The extent map of the file -- on which devices (and where on each device)
     each piece of the file resides.

WHAT IS THE EXTENT MAP?

A file is not necessarily built as a single contiguous chunk of disc space.  It
can be divided into up to 32 (on MPE/iX, even more) pieces called "extents".

It's conceivable that every extent in the file is on a different disc drive --
in fact, when the :STORE command (on MPE/V) shows you the "device number" on
which the file resides, it's only telling you the device on which the first
extent resides.  It's quite possible that all remaining extents actually reside
on other disc drives.

Therefore, before doing any "disc balancing" (for instance, using %ALTFILE
;DEV= to move IMAGE details onto one drive and masters onto another), you
should be certain which devices the file actually resides on.  The %LISTF ,4
listing (and also the %LISTF ,DISCUSE listing, which we'll discuss shortly) can
give you this information.

RELATED MPEX FEATURES

As we mentioned, %LISTF ,4 is often useful when you're doing %ALTFILE ;DEV=.
Also, the "best blocking factor" and "savable disc space" columns can give you
a good idea which files should be %ALTFILEd with ;BLKFACT=BEST and/or ;SQUEEZE.
On MPE/iX systems, any files that show some value in the "savable disc space"
column should be %ALTFILE ;XLTRIMed.

Selection criteria that you might want to use with %LISTF ,4 include:

   * ONDEVICE(x), which selects those files which have at least one extent on
     device x.

   * DEVICESECTORS(x), which returns the number of sectors of the file that
     reside on the given device --

        %LISTF @.DATA (DEVICESECTORS(1) >= SECTORS/2), 4

     will show the extent maps of those files at least half of whose sectors
     reside on device 1.

   * DEVICE, a string that contains the file's true device class --

        %LISTF @.DATA (DEVICE = "SYSDISC"), 4

     will find all the files built with ;DEV=SYSDISC.

   * BESTBLOCKFACTOR, the same best blocking factor value displayed by %LISTF
     ,4;

        %LISTF @.@(BESTBLOCKFACTOR <> BLOCKFACTOR), 4

     will find all the files whose blocking factor can be improved.

   * SECTORS, the number of sectors used by the file.

   * SAVABLESECTORS, the numbers of sectors savable by reblocking and
     SQUEEZEing (on MPE/V) or XLTRIMing (on MPE/iX).

Of course, like on all commands, any fileset with any selection criteria can be
used -- the ones we just listed are only those that are most applicable to
%LISTF ,4.


_LISTF_mode__5__735
%LISTF mode: 5

Syntax:   %LISTF fileset,5 [;listfile]
                           [;NOTOTALS|NORMTOTALS|ALLTOTALS]
                           [;NOPAGEHEAD]

Examples: %LISTF @.UTIL.SYS(ISPROG and PROG.PMCAP), 5

ACCOUNT=  SYS         GROUP=  UTIL

FILENAME  MAXDATA STACK DLSIZE DBSIZE #SEGS  CAPABILITIES

FILEUTIL     8192  1200    600   1231     3  BA IA PM PH [ZERODB]
SLEEPER   DEFAULT  1241      0    111     2  BA IA PM
SOO         20000  1200    768   2696    10  BA IA PM PH

%LISTF mode 5 shows you all about program files.  The most important things
here are:

   * The program's MAXDATA attribute, which indicates how large the program's
     stack can grow.

   * The capabilities with which the program was :PREPed -- PM (Privileged
     mode) capability is, of course, of particular interest.

Also included are:

   * DBSIZE, the size of the program's global variable area;

   * #SEGS, the number of segments in the program;

   * STACK and DL, the STACK= and DL= values the program was :PREPed with;

   * If the program was :PREPed with ;ZERODB, "[ZERODB]" is displayed after the
     capabilities.

Only program files are displayed -- any non-program files in the fileset are
simply skipped.

RELATED MPEX FEATURES

%listf ,5 is often used in conjunction with the %ALTFILE ;MAXDATA= and CAP=
keywords -- you can easily find out what MAXDATA= and capabilities a program
has, and then change them with %ALTFILE.

The other important use of %LISTF ,5 is finding programs that have the
sensitive PM and MR capabilities.  PM, of course, should be carefully
controlled because it gives a program complete power over the system; MR, if
improperly used, can make it easy for deadlocks to occur, which would require a
system restart to resolve.  For example, you might say:

   %LISTF @.@.@-@.PUB.SYS-@.@.VESOFT&
          (ISPROG and (PROG.PMCAP or PROG.MRCAP)),5

This will show you all the programs in the system (except those in PUB.SYS and
the VESOFT account) that use either PM or MR capability.


_LISTF_mode__6__FILENAME__or__QUALIFY__736
%LISTF mode: 6 [FILENAME] or [QUALIFY]

Syntax:   %LISTF fileset,6 [;listfile]
                           [;NOTOTALS|NORMTOTALS|ALLTOTALS]
                           [;NOPAGEHEAD]

Examples: %FILE FILELIST;TEMP;REC=-26,,F,ASCII;NOCCTL;DISC=16384,32
          %LISTF @.@.@(ACCDATE<TODAY-90 and NOT ISPRIV),6; *FILELIST

          (FILELIST will contain:
          AP000S.DEV.AP
          AP001S.DEV.AP
           ...
          )

"%LISTF fileset,6" will output (to $STDLIST or to the specified destination
file) the fully-qualified filenames of all the files in the given fileset.

This can be very useful for generating indirect files to be used by :STORE or
any other program that asks for a list of fully-qualified filenames.  For
example, our %MPEXSTORE command looks something like:

   %FILE FILELIST;TEMP;REC=-26,,F,ASCII;NOCCTL;DISC=16384,32
   %LISTF @.@.@(ACCDATE<TODAY-90 and NOT ISPRIV),6; *FILELIST
   %STORE !FILELIST; *T; SHOW

will store all the non-database files that haven't been accessed in the past 90
days.

The :STORE command can't handle an MPEX fileset (with its selection criteria),
but it can take an indirect file (a file containing filenames).  We then use
MPEX's %listf ,6 to create an indirect file and then feed this indirect file to
the :STORE command.

Note, however, that if you want to use %LISTF ,6 to create such an indirect
filename list, you must specify ;NOCCTL on the :FILE-equation for the list
file.


_LISTF_mode___1__LABEL__737
%LISTF mode: -1 [LABEL]

Syntax:   %LISTF fileset,-1 [;listfile]
                            [;NOTOTALS|NORMTOTALS|ALLTOTALS]
                            [;NOPAGEHEAD]

Examples: %LISTF MYFILE, -1

%LISTF ,-1 is very similar to the MPE :LISTF ,-1 (which shows the exact
contents of a file label) except that MPEX's %LISTF can work on MPEX filesets.
To do a %LISTF ,-1 of a file, you must either have SM capability or have AM
capability in the file's account.

%LISTF ,-1 is included mostly for compatibility and completeness; typically,
all the information you need to know is available far more clearly from one of
the other %LISTF modes.


_LISTF_mode___2__ACD__738
%LISTF mode: -2 [ACD]

Syntax:   %LISTF fileset,-2 [;listfile]
                            [;NOTOTALS|NORMTOTALS|ALLTOTALS]
                            [;NOPAGEHEAD]

Examples: %LISTF @.DATA-AP@.DATA(ACCESSIBLE("R")), -2

FILENAME        ------------ACD ENTRIES--------------

CONTROL             @.PROD              : R
                    JACK.PROD           : R,W,X,A,L,RACD
                    LEARN.PROD          : NONE
                    OPERATOR.SYS        : R,RACD
DATATEST            NO ACDS
D770UPD             NO ACD ACCESS
...

%LISTF @.@.@(HASACD), -2
          << shows ACD information on all files in the system that >>
          << have an ACD >>

%LISTF ,-2 shows the Access Control Definitions (ACDs) of files in an MPEX
fileset.

The output of %LISTF ,-2 is just like the output of MPE's :LISTF ,-2 except
that, of course, MPEX %LISTF lets you use MPEX filesets, with selection
conditions (such as ACCESSIBLE("R"), which means "all files that I can read"),
+ filesets, and - filesets.

Just like MPE :LISTF ,-2, MPEX shows "NO ACDS" when a file has no ACD and "NO
ACD ACCESS" when a file has an ACD but you are not authorized to see it.


_LISTF_mode___3__DETAIL__w_lockwords__739
%LISTF mode: -3 [DETAIL] w/lockwords

Syntax:   %LISTF fileset,-3 [;listfile]
                            [;NOTOTALS|NORMTOTALS|ALLTOTALS]
                            [;NOPAGEHEAD]

Examples: %LISTF MYFILE, -3

********************
FILE MYFILE.DEV.VESOFT

FILE CODE : 1029                 FOPTIONS: BINARY,FIXED,NOCCTL,STD
BLK FACTOR: 1                    CREATOR : MANAGER
REC SIZE: 256(BYTES)             LOCKWORD: MYLOCK
BLK SIZE: 256(BYTES)             SECURITY--READ:    ANY
EXT SIZE: 1529(SECT)                       WRITE:   ANY
NUM REC: 1528                              APPEND:  ANY
NUM SEC: 1529                              LOCK:    ANY
NUM EXT: 1                                 EXECUTE: ANY
MAX REC: 1528                            **SECURITY IS ON
MAX EXT: 1                       FLAGS   : n/a
NUM LABELS: 0                    CREATED : TUE, JAN 26, 1991
MAX LABELS: 0                    MODIFIED: TUE, JAN 26, 1991, 1:52 PM
DISC DEV #: **                   ACCESSED: TUE, JAN 26, 1991
CLASS     : DISC                 RESTORED: TUE, JAN 26, 1991, 1:35 PM
SEC OFFSET: 1                    LABEL ADDR: %00100610103

%LISTF ,-3 is exactly like %LISTF ,XL3 except that it shows the lockwords (if
any) of the files listed, and it lets you use MPEX filesets.  This is much like
MPE/iX's :LISTF ,-3, which in turn is patterned after LISTDIR5's >LISTF ;PASS.

Needless to say, this mode can only be used by users with SM capability or by
users with AM capability listing files in their own accounts.


_LISTF_mode__ACCESS__740
%LISTF mode: ACCESS

Syntax:   %LISTF fileset,ACCESS [;listfile]
                                [;NOTOTALS|NORMTOTALS|ALLTOTALS]
                                [;NOPAGEHEAD]

Examples: %LISTF MYFILE, ACCESS

ACCOUNT=  PROD        GROUP=  DATA

FILENAME  ---TYPE-- JOBNUM PIN  ----PROGRAM---- ACCESS  RECORD -LOCK-

MYFILE    OPENED    #S141  16   AP000.PUB.PROD  INPUT       16
                                tim,clerk.payroll,pub (ldev 24)
          OPENED    #J478  39   AP090.TEST.PROD APPEND     127
                                update,mgr.dev,test
          OPENED    #S193  55   AP000.PUB.PROD  INPUT       18
                                laura,clerk.payroll,pub (ldev 37)

%LISTF ,ACCESS may well be one of the most internally complicated -- and one of
the most useful -- MPEX commands.  It lets you see exactly who is accessing
(and locking) a particular MPE or KSAM data file.  In particular, it shows you:

   * What they're doing to the file -- opening it, running it, storing it,
     restoring it, etc.;

   * Who they are -- their job/session numbers, logon IDs, program names, and
     PINs;

   * How they're accessing it (INPUT, OUTPUT, APPEND, etc.);


MPE_V_and_MPE_iX_differences___LISTF__741
MPE/V and MPE/iX differences: %LISTF
   * Where they are in the file (the record number of the most currently read
     record) -- very useful if somebody is reading a file sequentially and you
     want to see how far they've gotten.  Note: the current record number is
     not available for MPEX/XL "mapped" files (which includes IMAGE databases),
     due to operating system limitations.


MPE_V_and_MPE_iX_differences___LISTF__742
MPE/V and MPE/iX differences: %LISTF
   * Whether or not the user is locking the file, or perhaps waiting on a file
     lock (in which case it'll tell you what order it is in the wait queue!).
     Note: file locking information is not available on MPE/iX systems, due to
     operating system limitations.

There are many applications for this sort of capability.  Some common ones
include:

   * You want to access the file exclusively (purge it, rename it, modify it,
     restore over it, store it, etc.) and the system says that somebody else
     has it open.  Who is it? If you only knew, you could just get him to close
     it -- ask him to exit his program for a moment -- but normal MPE gives you
     no way of finding it out.  With %LISTF ,ACCESS, you can do this in one
     command.

   * You're running a big batch serial read and you're getting impatient.  How
     far has it gotten? Just do a %LISTF ,ACCESS and look at its current record
     number! (This is also quite useful for checking the progress of your batch
     compiles.)

   * You're using MPE file locking on MPE or KSAM files and sessions are
     beginning to hang.  Who's got the file locked? Maybe they're at a terminal
     read and have gone to lunch! %LISTF ,ACCESS will tell you who the locker
     is, who the waiting processes are, and in what order the processes are in
     the wait queue.

This is information you couldn't get anywhere else in MPE, and it just might
save your skin some time!

DATABASES

Before TurboIMAGE, %LISTF ,ACCESS worked just fine with databases -- databases
and their datasets are, after all, just plain MPE files; what works on files
will work on databases, too.  (%LISTF ,ACCESS will also work very well on
TurboIMAGE/XL.)

Unfortunately, TurboIMAGE/V uses a special mechanism called "global FOPEN":
instead of having each database user open each dataset that he's using, each
dataset is opened once (or, sometimes, 3 times) by the system.

What can %LISTF ,ACCESS do? It can search the entire system for accessors of
the dataset and not find anybody in particular, since no specific process
actually has the dataset FOPENed.  For a dataset, all that it can display is
that it is "GLOBALLY OPENED" and the current record number in the dataset
(useful only if only one process is accessing that dataset).

For a database root file, things are better, because a root file is opened by
each accessing process.  If you do a

   %LISTF APBASE,ACCESS

against a root file, you'll see the vital statistics (session number, logon ID,
program name, and PIN) of every database accessor (sometimes more than once,
since IMAGE may issue more than one FOPEN per process against the same root
file).

If you're using TurboIMAGE/V, we recommend you just do a DBUTIL >>SHOW USERS
and/or >>SHOW LOCKS.  They're specifically tailored for IMAGE databases, and
work quite well for them; MPEX's %LISTF ,ACCESS does roughly the same thing for
MPE files and KSAM files.

As we mentioned before, %LISTF ,ACCESS will again give you a lot of useful
information on MPE/iX machines with TurboIMAGE/XL.  It's only for TurboIMAGE/V
that %LISTF ,ACCESS's output is somewhat restricted.

PERFORMANCE NOTES

As we mentioned before, %LISTF ,ACCESS is in some respects the most internally
complicated of MPEX's commands.  MPE does not make it easy for us to do a
%LISTF ,ACCESS; we have to read every open file entry in the stack of every
process to find out which processes have the file open.

This can take a substantial amount of time.  %LISTF ,ACCESS is much faster than
in some previous versions, but it could still take up to a minute or so on a
heavily loaded system.  It will not lock down any resources, but it will take
some time and processing power.

To optimize %LISTF ,ACCESS, we try to read as much data as possible from each
data segment we look at (to avoid having to look at the data segment again
later); to do this, though, we need a good deal of stack space.

If you get a stack overflow abort while doing a %LISTF ,ACCESS, you can tell
MPEX to decrease the size of each chunk that it reads from a data segment, thus
slowing the command down a bit but possibly avoiding the stack overflow.  You
can control the chunk size by saying


MPEXLISTFACCESSCHUNKSIZE_743
MPEXLISTFACCESSCHUNKSIZE


Stack_overflows_in__LISTF__744
Stack overflows in %LISTF

     :SETJCW MPEXLISTFACCESSCHUNKSIZE=number

The default value is 4096; you can (without too badly affecting performance)
set this to 2048 or even 1024 if necessary; this can save enough stack space to
avoid stack overflows.

%LISTF ,ACCESS stack overflows should, in any event, be rare; they most
frequently happen when the %LISTF ,ACCESS is being done from within a UDC or as
a result of a %REDO (or %DO) command, since UDCs and %REDOs already require a
good deal of stack space for themselves.


_LISTF_mode__DATES_745
%LISTF mode: DATES

Syntax:   %LISTF fileset,DATES

Examples:
%LISTF MPEX@,DATES

SYSTEM BATMAN   TOM,MANAGER.VESOFT,PUB   TUE, NOV 30, 1993,  9:48 AM

ACCOUNT=  VESOFT      GROUP=  PUB

File        Created    Modified     Accessed   Restored  State-Change
-------- ----------  ----------  -----------  ---------  ------------
MPEX     1/20 11:15   Wed 11:15  Today  9:36  Tue 11:15     Wed 11:15
MPEXMGR   Wed 12:20   Wed 12:20  Today  9:37  Wed 12:20     Wed 12:20

The MPEX %LISTF mode DATES is an updated and easier-to-read version of MPEX
%LISTF mode 3.  This %LISTF mode uses the current setting of the %SET DATE
command to determine the proper format for displaying dates more than a week
old.  For dates within the last week, the day of the week is displayed using a
three letter abbreviation.  However, for dates older than a week but still in
the current year, the date is displayed as MM/DD if the date setting is MDY or
YMD or as DD/MM for %SET DATE,DMY.  For dates prior to the current year, a
six-digit number is displayed without slashes, either in MMDDYY, DDMMYY or
YYMMDD format depending upon what was set using the %SET DATE command.

On systems that support POSIX, an additional column labeled "State-Change" is
displayed showing the files state-change date.


_LISTF_mode__DB_746
%LISTF mode: DB

Syntax:   %LISTF fileset,DB [;listfile]
                            [;NOTOTALS|NORMTOTALS|ALLTOTALS]
                            [;NOPAGEHEAD]

Examples: %LISTF @.DATA(DBSETFULLNESS>.65 and MODDATE>TODAY-90), DB

ACCOUNT=  PROD        GROUP=  DATA

FNAME SET NAME TYPE LDEV  ENTRY CAPA-  %FULL BLK SECTORS %BLOCK SECTRS
                          COUNT  CITY        FCT         WASTED WASTED

ADVT01 CUST       M   3     943  1001  94.2%  16    1024   0.7%      7
ADVT02 SUPPLY     M        1063  1511  70.3%  51     434   0.1%      0
ADVT03 SALES      D   2     199   210  94.7%  14     256   0.1%      0

CUST01 CUST       M        9576 13001  73.6%  23   11340   0.2%     22
CUST02 SUPPORT    D        5618  8004  70.1%   6   13350  12.7%   1699
CUST09 AUX-CUST   D   1     525   634  82.8%   2    2544   5.6%    143
CUST10 LINES      D   2     321   476  67.4%   2    1912   0.1%      1
CUST11 TECH       M        9145 11149  82.0%  73    3080   0.0%      0

As you see, %LISTF ,DB shows you a lot of useful information on IMAGE DATABASE
DATASETS:

   * The dataset's filename and IMAGE dataset name.

   * The dataset type (D=detail, M=manual, A=automatic).

   * The LDEV the dataset is on, if it is entirely on a single LDEV; otherwise
     blank.

   * The number of entries in the dataset, the dataset capacity, and the
     percentage full of the dataset.

   * The dataset blocking factor (number of records per IMAGE block).

   * The number of sectors in the dataset.

   * The fraction of space that is wasted in each block (because the total size
     of the data in each block [including IMAGE pointers] is not an exact
     multiple of 128 words).

   * The total number of sectors wasted because the total data size in each
     block is not an exact multiple of 128 words.

     The major advantages of this mode are the obvious ones:

   * You can now see the status of all the databases in your system (or in a
     particular fileset).

   * You can select datasets by various things, especially their fullness:

        %LISTF @.@.@(DBSETFULLNESS>.70 and DBSETTYPE<>"D"), DB

     will find all the master (DBSETTYPE<>"D") datasets in the system that are
     more than 70% full (since access speed to highly-loaded master datasets
     can be pretty bad).

   * You can easily see the percentage fullness and the blocking factor of each
     dataset.

RELATED MPEX FEATURES

Certain selection criteria fit very nicely with %LISTF ,DB:

   * Selection by DBSETFULLNESS (see the example above);

   * Selection by DBSETTYPE:

        %LISTF @.@.@(DBSETTYPE<>"D"), DB

     finds all the non-detail (i.e.  manual or automatic) datasets.  As you
     see, DBSETTYPE is always one-character string -- "D" for detail, "M" for
     manual, and "A" for automatic.

   * Selection by DBSETNAME, used if you want to show information on a specific
     dataset:

        %LISTF BASEAP@(DBSETNAME="INVOICES"), DB

     Similarly, you might even say

        %LISTF BASEAP@(DBSETNAME MATCHES "INV@"), DB

     to show information on all datasets whose names start with INV.  This way
     you can avoid having to figure out the dataset's MPE file name (e.g.
     BASEAP09).

   * If you want to, you can also select on DBSETENTRIES (current number of
     entries), DBSETCAPACITY (capacity), DBSETBLOCKFACTOR (dataset blocking
     factor), DBSETENTRYLENGTH (number of words per IMAGE record), and
     DBSETBLOCKWASTAGE (the fraction of space wasted because the block size is
     not a multiple of 128 words).

MPEX can get database information on any database (except for those that are
exclusively opened), subject to the normal MPE file system security
restrictions.

NOTES ON DBOPEN MODES

Unfortunately, some DBOPEN modes are incompatible with one another -- if, for
instance, you open a database in mode 1, you can't then open it in mode 2
(until the original opener closes it), and vice versa.

Although %LISTF ,DB doesn't use DBOPEN to look at the databases, its FOPEN call
is roughly equivalent to a DBOPEN mode 6 (which is compatible with modes 2, 4,
and 8, but not with modes 1 and 5).  If, however, this fails because the
database is already opened in mode 1 or 5, %LISTF ,DB is smart enough to try
opening the database the other way, which is compatible with modes 1 and 5.

Unfortunately, if MPEX opens the database when it is not opened by anybody
else, and then somebody else tries to open it in mode 1 or 5, the would-be
opener will get an IMAGE error -1, "DATA BASE OPEN IN AN INCOMPATIBLE MODE" --
MPEX didn't know that somebody would try to open the database in mode 1 or 5,
so it opened it in mode 6.  (This will only happen until MPEX closes the
database, which it will do when MPEX starts listing the next database in the
fileset or when the %LISTF ,DB finishes.)


MPEXLISTFDBMODE5_747
MPEXLISTFDBMODE5
If you are concerned that this might happen, and you only open your databases
in modes 1 or 5, you can set the MPEXLISTFDBMODE5 JCW to 1 (perhaps in your
MPEXMGR.PUB.VESOFT file).  This tells %LISTF ,DB to open databases in a way
analogous to a DBOPEN mode 5 (read only, compatible with modes 1 and 5, but
incompatible with the other modes).


_LISTF_mode__DISCUSE__748
%LISTF mode: DISCUSE


Disc_space__listing_by_disc_drive_749
Disc space: listing by disc drive

Syntax:   %LISTF fileset,DISCUSE [;listfile]
                                 [;NOTOTALS|NORMTOTALS|ALLTOTALS]
                                 [;NOPAGEHEAD]

Examples: %LISTF @.DATA, DISCUSE

ACCOUNT=  VESOFT      GROUP=  DEV

FILENAME  CODE     REC  TYPE     DEV 1   DEV 2  DEV 11

ACC       171     508B  VA          50
BEXP              256W  FB         420     840      60
BHOOKU            256W  FB          40      80
BPROCSRL  PROG    128W  FB                         795
BRLMPE            256W  FB         120     280
CADDRL             72B  FA           2
CCALC              72B  FA                  10
CCONVEXP          256W  FB          60      30
...

GROUP TOTAL                      12317    9422    1529

MPEX's %LISTF ,DISCUSE is an invaluable tool if you care about which files are
on which disc drives.  For each file in the fileset, it shows you how many of
its sectors are on each device; it also prints group, account, and grand
totals, for each device.

Some examples of possible uses are:

   %LISTF BASEAP@.DATA.AP, DISCUSE

to show where each of your BASEAP datasets is located; or,

   %LISTF @.@.@(ONDEVICE(1)), DISCUSE

to show all the files that are at least partly on the system disc (ONDEVICE(1))
-- the DISCUSE listing will tell you exactly how much of each file is on the
system disc and how much is on other discs.


_LISTF_mode__ID_750
%LISTF mode: ID

Syntax:   %LISTF fileset, ID

Examples: %LISTF @.PUB.VESOFT, ID

MPEX %LISTF @.PUB.VESOFT   PAGE 1
SYSTEM DEVELOP  TOM,MANAGER.VESOFT,WORKTE   FRI, NOV  5, 1993,  3:42 PM

FILENAME  CODE     REC  TYPE   EOF  SECT DAYS SINCE
                  SIZE                    ACC  MOD

BASIC     PROG    128W  FB     360   368   25   25  Hooked BASIC.PUB.SYS
BYEUDC             72B  FA      13    16   25   25  LOCKOUT
                                                      OPTION LOGON
                                                      COMMENT  This UDC
CI        PROG    128W  FB      11    16    1   25  Command Interpreter
CIMGR             256B  FA       3    16    1   25  :INITUDCS
                                                      :INITMPEXMGR
                                                      :INITREDO
DATAFILE          256B  VA       7   256            Encrypted Today at 15:23 by
                                                    TOM,MANAGER.VESOFT
EDITOR    PROG    128W  FB     307   320    1   25  HP32201
FONEDB    PRIV    128W  FB       6    16   73   73  Telephone database
FONEDB01  PRIV    512W  FB      35   144   73   73  NOTES (master)
FONEDB02  PRIV    384W  FB       6    32   73   73  A-KEY (auto)
FONEDB03  PRIV    512W  FB      10    48   73   73  PHONES (detail)
FONEDBVE           72B  FA       2    16   73   73  $user @.@
                                                      $program query.pub
                                                      $class 1
QEDITMGR  QEDIT    80B TEXT     31    16        20  /set addcurrent
                                                    /set check delete
                                                    /set decimal
QEDJUMBO  QEDIT  1000B DATA      5    16   23   31  This is an example of
                                                   a QEDIT "JUMBO" file
                                                   (longer records,etc.)
...

In addition to the basic %LISTF ,2 information shown for each file, this %LISTF
mode displays extended descriptions or a portion of the file to help you to
easily identify each file.

This identifying information is retrieved from within files without modifying
their last-access date and time.


_LISTF__751
%LISTF
Note that for QEDIT files, as shown in the above example, the SIZE, TYPE, and
EOF columns display more descriptive information.  The SIZE is the actual
record size, the TYPE is the internal file type, and the EOF is the actual
number of logical lines in the file.

For "jumbo" QEDIT files, (files that can have more than 65,535 lines and/or
records wider than 256 characters), we add a "+" after "QEDIT" in the CODE
column.

For files that have been encrypted using the %SEC ENCRYPT command, a two-line
display is generated showing the date, time, and user ID of the person who
encrypted the file.  Note that a specific description created using the
%IDENTIFY command will override this display.

If you have used %IDENTIFY to create an extended description for the file, then
the extended description you have applied to this file will be displayed.
Although the description that you create using %IDENTIFY may be up to 80
characters, descriptions longer than 31 characters will "wrap around" to the
next line on an 80 column display (of course, if you send the listing to the
line printer, then the line can be up to 78 characters before it wraps around
to the next line).

If you have not added your own description of the file and the file is a
dataset within a DATABASE, then information about the dataset will be
displayed, such as the name of the set and whether or not it is a master or
detail dataset.  For CM programs without an extended description, the name of
the outer block will be displayed if it is defined.  For all other files, the
contents of the first three lines of the file will be displayed.


IDCONTAINS_752
IDCONTAINS
A useful application of the %IDENTIFY command and this %LISTF mode is to use a
"keyword" when describing your files.  You can then use the IDCONTAINS(...)
function or the %FILTER command to limit the listing to only those files
related to a particular command or application.  Here are some useful examples:

     %LISTF @.PUB.SYS(IDCONTAINS("SQL")),ID
       Shows all SYSTEM files related to the SQL subsystem

     %LISTF @.@.VESOFT(IDCONTAINS("Obsolete")),ID
       Shows all files in the VESOFT account that are OBSOLETE

     %FILTER "LISTF @.MYBASE,ID",DELIM "AP"
       Shows all files with the keyword "AP" in their description
       (The "delim" keyword avoids descriptions like "CAPTURED TEXT")


_LISTF_mode__SAVABLE__753
%LISTF mode: SAVABLE

Syntax:   %LISTF fileset,SAVABLE [;listfile]
                 [;NOTOTALS|NORMTOTALS|ALLTOTALS]
                 [;NOPAGEHEAD]

Examples: %LISTF @.@.@, SAVABLE

Group DATA    .DEV     has  10256 savable sectors out of  25984
  Group USL     .DEV     has  42240 savable sectors out of  59680
Account          DEV     has  52496 savable sectors out of  85664
...
Fileset                  has 274224 savable sectors out of 986240

%LISTF ,SAVABLE shows you how much disc space can be saved in a fileset
(usually @.@.@, meaning your entire system) by using

%ALTFILE fileset;BLKFACT=BEST;SQUEEZE                      on MPE/V systems

%ALTFILE fileset;XLTRIM                                    on MPE/iX systems

The savable disc space is shown by group, by account, and for the entire system
-- we show you both the savable and the total space.

This is especially useful in MPE/iX systems because %ALTFILE ;XLTRIM (available
only on MPE/iX systems) is so safe -- its only effect is to save the space used
by the file, without making the file inaccessible in any way and without even
restricting its further growth (which an %ALTFILE ;SQUEEZE would do).  You
might very well want to say

   %ALTFILE @.@.@(SAVABLESECTORS>16);KEEPAMDATES;XLTRIM

to trim all the files on your system that are using more disc space than
necessary.

On MPE/V systems, you'd have to use %ALTFILE ;BLKFACT=BEST;SQUEEZE to get rid
of this wasted disc space; unfortunately, ;BLKFACT=BEST and ;SQUEEZE have side
effects that you should think about before using them.  We suggest that you
read the ";BLKFACT=", ";SQUEEZE", and ";EXTENTS=" (another disc-space-saving
option) sections of the %ALTFILE command description in this manual for more
information.


_LISTF_mode__SEC_754
%LISTF mode: SEC

Syntax:   %LISTF fileset,SEC [;listfile]
                             [;NOTOTALS|NORMTOTALS|ALLTOTALS]
                             [;NOPAGEHEAD]

Examples: %LISTF @.DATA, SEC

ACCOUNT=  VESOFT      GROUP=  DATA

FILENAME  CODE   TYPE  READ     APPEND   WRITE    LOCK      EXECUTE

LOG20            FBO   !!!      !!!      !!!      !!!       RELEASED!
LOGOFF           FA    ANY      ANY      ANY      ANY       ANY
MEMOFORM         FA    ANY      AC       AC       AC        AC
VEOPNTS   EDTCT  FA    AC       AC       CR       CR        CR
VEOPNTVE         FA    ANY      AL,GU    CR       AL,GU     AL,GU

%LISTF ,SEC shows information on file security.  It shows both the
:RELEASE/:SECURE status (in the above example, LOG20 is released -- all the
other files are secured) and the security matrix of the file (set by :ALTSEC).

As you may know, you can separately allow READ, APPEND, WRITE, LOCK, and
EXECUTE access to a file.  By default, anybody can do anything to a file
(subject to the security attributes of the file's group and account) --
however, the :ALTSEC command can be used to change this.  For instance, the
VEOPNTVE file shown above must have been :ALTSECed by a command such as:

   :ALTSEC VEOPNTVE;(R:ANY;A,L,X:AL,GU;W:CR)

and is, in fact, a probable security breach.
(Files with the same name as the root file of a database but ending with "VE"
are usually used by our VEOPEN routine to protect database access.  See the
SECURITY manual for details on the use of VEOPEN and access control files.)

Normally, the information %LISTF ,SEC shows can only be gotten from LISTDIR5's
>LISTF or >LISTSEC commands (or MPE/iX's :LISTF ,3 and :LISTF ,4).  However,
%LISTF ,SEC is the only command that shows the data in a one line-per-file
format (much easier to read than LISTDIR5's or MPE/iX :LISTF's print-outs).
Furthermore, %LISTF ,SEC merges the file security matrix, the group security
matrix, and the account security matrix, thus showing the true effective
security of the file.

Sometimes, the information reported by %LISTF ,SEC will appear slightly
different from that shown by LISTDIR5 or MPE/iX :LISTF.  For instance, LISTDIR5
might say that read access on a file is allowed to "AC,GU,CR" -- %LISTF ,SEC
will show this simply as "AC".

This is because AC (account) access implicitly allows GU and CR access, too;
thus "AC,GU,CR" is redundant, and is equivalent to just "AC".  Although %LISTF
,SEC's and LISTDIR5's outputs appear different, they're really identical.

RELATED MPEX FEATURES

%LISTF ,SEC works closely with:

   * The %RELEASE and %SECURE commands -- if, for instance, %LISTF ,SEC shows
     you a lot of released files in a group, you can say:

        %SECURE @.DATA(ISRELEASED)

which will :SECURE all the released files in the DATA group.

   * The %ALTSEC command can :ALTSEC entire filesets, as well -- after looking
     at a %LISTF ,SEC listing, you might decide to :ALTSEC the entire fileset:

        %ALTSEC @.DATA;(R:ANY;A,W,L,X:GU,CR)

   * The SECURITYANY, SECURITYAC, SECURITYAL, SECURITYGU, SECURITYGL, and
     SECURITYCR selection criteria -- each of these is a string that contains
     (or doesn't contain) the characters "R", "A", "W", "X", or "L" depending
     on whether or not this access mode is allowed to this class of user.

     For instance, if SECURITYANY = "R", this means that the only thing that
     all users may do is Read the file; the other access types are allowed to
     more restrictive access classes (e.g.  AC users only or GU users only).

     For example,

        %LISTF @.DATA(POS("R",SECURITYANY)=0),SEC

     will find and list all the files in the DATA group that do not allow R
     access to ANY.  POS("R",SECURITYANY) finds the location of the first
     occurrence of the character "R" in SECURITYANY -- if there is no "R", POS
     returns a 0.

     Thus, POS("R",SECURITYANY)=0 means "there is no 'R' in SECURITYANY", i.e.
     Read access is not allowed to ANY.

   * The SECURITYR, SECURITYA, SECURITYW, SECURITYL, and SECURITYX selection
     criteria -- each of these is a string that contains (in the same format as
     in the %LISTF ,SEC listing) the classes of users that are allowed this
     type of access.

     For instance, if SECURITYR = "AC", this means that only users in the
     file's account are authorized to read the file.


_LISTF_mode__XL3__755
%LISTF mode: XL3

Syntax:   %LISTF fileset,XL3 [;listfile]
                             [;NOTOTALS|NORMTOTALS|ALLTOTALS]
                             [;NOPAGEHEAD]

Examples: %LISTF MYFILE, XL3

********************
FILE MYFILE.DEV.VESOFT

FILE CODE : 1029                 FOPTIONS: BINARY,FIXED,NOCCTL,STD
BLK FACTOR: 1                    CREATOR : MANAGER
REC SIZE: 256(BYTES)             LOCKWORD: **
BLK SIZE: 256(BYTES)             SECURITY--READ:    ANY
EXT SIZE: 1529(SECT)                       WRITE:   ANY
NUM REC: 1528                              APPEND:  ANY
NUM SEC: 1529                              LOCK:    ANY
NUM EXT: 1                                 EXECUTE: ANY
MAX REC: 1528                            **SECURITY IS ON
MAX EXT: 1                       FLAGS   : n/a
NUM LABELS: 0                    CREATED : TUE, JAN 26, 1991
MAX LABELS: 0                    MODIFIED: TUE, JAN 26, 1991, 1:52 PM
DISC DEV #: **                   ACCESSED: TUE, JAN 26, 1991
CLASS     : DISC                 RESTORED: TUE, JAN 26, 1991, 1:35 PM
SEC OFFSET: 1                    LABEL ADDR: %00100610103

The XL3 listing mode is very much like MPE/iX's :LISTF ,3 (which in turn is
very much like LISTDIR5).  Of course, its big advantage is that it supports the
full power of MPEX filesets.


_LISTF_mode__XL4__756
%LISTF mode: XL4

Syntax:   %LISTF fileset,XL4 [;listfile]
                             [;NOTOTALS|NORMTOTALS|ALLTOTALS]
                             [;NOPAGEHEAD]

Examples: %LISTF MYFILE, XL4

FILE: MYFILE.WORK.VESOFT

ACCOUNT ------  READ : ANY
               WRITE :
              APPEND :
                LOCK : ANY
             EXECUTE : ANY

GROUP --------  READ : GU
               WRITE : GU
              APPEND : GU
                LOCK : GU
             EXECUTE : GU
                SAVE : GU

FILE ---------  READ : ANY                FCODE: 0
               WRITE : AC               **SECURITY IS ON
              APPEND : AC
                LOCK : AC
             EXECUTE : ANY

FOR MANAGER.VESOFT: READ, WRITE, APPEND, LOCK, EXECUTE

The XL4 listing mode is very much like MPE/iX's :LISTF ,4 (which in turn is
very much like LISTDIR5's >LISTSEC).  Of course, its big advantage is that it
supports the full power of MPEX filesets.

Additionally, rather than just giving you the "raw" information about the
file's access mask -- e.g.  that Write access was granted to AC, AL, and GL --
it gives you the file's "true" access information, in this case that Write
access is actually granted to AC; after all, since AL and GL are subsets of AC,
saying "AC, AL, and GL" would be redundant.

Similarly, if a file is built with Write access granted to AC and Lock access
granted to GU only, MPEX's %LISTF ,XL4 will show it as "LOCK:AC".  This is
because Write access implies both Lock and Append access; if you configure Lock
or Append access as being more restrictive than Write access, this
configuration won't really take effect.

Thus, our output might look somewhat different from the MPE/iX :LISTF ,4 output
or LISTDIR5's >LISTSEC output; however, we believe that our output is actually
more informative.


_LISTF_mode__defining_your_own_formats__757
%LISTF mode: defining your own formats


Flexible__LISTF_758
Flexible %LISTF

Syntax:   %LISTF fileset, listfgroupfile|^formatfile
                          [;listfile]
                          [;NOTOTALS|NORMTOTALS|ALLTOTALS]
                          [;NOPAGEHEAD]

Examples: %LISTF @.@.AP, ^MYLISTF.DATA.PROD; *LP
          %LISTF @.@.AP, SUPER    << uses your own file >>
                                  << SUPER.LISTF.VESOFT >>

   Note: This is one of the most sophisticated features of MPEX.  It can be
         very powerful, but also fairly difficult to use.  Beginning users
         should probably skip this section.

In addition to providing you with many powerful LISTF modes, MPEX lets you
define your own.  You can set up your own "flexible %LISTF format files" that
define how you want the output to look; these files essentially contain little
PASCAL-like programs that give you all the power of a high-level programming
language.

Most of the syntax elements of these files are described in the Advanced
Expression Programming chapter of the Appendix to this manual -- this will
explain the various operators and statements (like IF/THEN/ELSE, WHILE/DO, VAR,
etc.) that you have available.  You can also look at the files in the
LISTF.VESOFT group to see how MPEX implements its built-in %LISTF modes.

Once you write a flexible %LISTF format file, you can use it by specifying its
filename (prefixed by a "^") as the "mode" parameter of a %LISTF command:

   %LISTF @.@.AP, ^MYLISTF.DATA.PROD; *LP

You may also put the file in the LISTF.VESOFT group -- in this case, all you
need to do is specify the unqualified file name:

   %LISTF @.@.AP, SUPER

will use the flexible %LISTF file called SUPER.LISTF.VESOFT.  In fact, all the
MPEX %LISTF modes are implemented by flexible %LISTF format files in the
LISTF.VESOFT group -- DB.LISTF.VESOFT implements the DB mode,
DISCUSE.LISTF.VESOFT implements the DISCUSE mode, etc.  A word of warning is in
order here: when upgrading to new releases of our software, we will not make
any attempt to preserve any %LISTF files that you may have created and placed
in this group.  In fact, it is quite possible that we may eventually choose the
same name that you have in order to define a new %LISTF format.  In that case,
our future installation will overwrite your handiwork.  So while it may be
convenient to use this group, we do not recommend that you place any files
here.

Since MPE filenames can't start with digits or special characters, all the
numeric modes (0, 1, 2, etc.) are prefixed with Ns in the LISTF.VESOFT group
(mode 3 is implemented by N3.LISTF.VESOFT).  Similarly, the negative modes are
prefixed with Ms (mode -1 is implemented by M1.LISTF.VESOFT).

How is a flexible %LISTF template file implemented? It's an ordinary
EDITOR-format file that contains a sequence of statements of the type described
in the Advanced Expression Programming chapter of the Appendix.  The file can
therefore define its own local variables, use control structures like
IF/THEN/ELSE, WHILE/DO, and so on.  More importantly, it can reference all the
"FILE ATTRIBUTE VARIABLES" pertaining to the current file just like you can in
selection conditions.

For instance, the N2.LISTF.VESOFT file (which implements %LISTF ,2) has a
statement in it that says:

   WRITELN (FILE:8,
            FMTOPENED:2,
            CODE:6,
            FMTRECSIZE:6:'RIGHT',
            '  ', FMTTYPE:4,
            EOF:10,
            FLIMIT:11,
            BLOCKFACTOR:4,
            SECTORS:9,
            ' ', NUMEXTENTS:2,
            IF MAXEXTENTS=0 THEN '  *' ELSE STRWRITE(MAXEXTENTS:3)
            );

This is what generates the detail lines of a %LISTF ,2, e.g.

   SL      * SL      128W  FB        9768      65535   1    10084  4 26

The WRITELN statement takes all the specified file attribute variables and
formats them to be output.

The Advanced Expression Programming chapter of Appendix describes various
control structures, but does not mention the most important one: FOR RFILE IN
...  This construct is used in a flexible %LISTF file to repeat something for
all the files in the fileset.  The reason that this is only mentioned here is
because this is a special statement that is valid only in %LISTF expression
files.


FOR_RFILE_IN____759
FOR RFILE IN...


MPEXFILESETTOTAL_760
MPEXFILESETTOTAL

    FOR RFILE IN MPEXFILESETTOTAL
      DO
        BEGIN
        statement;
        ...
        statement;
        END;

If you look at the LISTF.VESOFT files, you'll find that almost all of them use
this statement.  It simply means "For each file in the current fileset, do the
statements between the 'BEGIN' and the 'END'".  A typical flexible LISTF file
might look like:


MPEXHEADER1_761
MPEXHEADER1


MPEXHEADER2_762
MPEXHEADER2


MPEXHEADER3_763
MPEXHEADER3

   statements to do at the beginning of the %LISTF operation;
   MPEXHEADER1:="headerline1";
   MPEXHEADER2:="headerline2";
   MPEXHEADER3:="headerline3";
   FOR RFILE IN MPEXFILESETTOTAL
     DO
       BEGIN
       statement;
       ...
       statement;
       END;
   statements to do at the end of the %LISTF operation;

The MPEXHEADER1, MPEXHEADER2, and MPEXHEADER3 variables are set to the header
lines that you want to output for each group (and at the top of each page); the
statements between BEGIN and END indicate what is to be printed for each file.
MPEX automatically takes care of writing the "ACCOUNT= ...  GROUP= ..."
headers, the group/account/grand totals, and the page breaks.

For example, %LISTF mode 1 is implemented by the N1.LISTF.VESOFT file, which
looks something like this:

   MPEXHEADER1:="FILENAME  CODE  ------------LOGICAL RECORD--------";
   MPEXHEADER2:="                  SIZE  TYP        EOF      LIMIT ";
   MPEXHEADER3:="";
   FOR RFILE IN MPEXFILESETTOTAL
     DO
       BEGIN
       WRITELN (FILE:8,
                FMTOPENED:2,
                CODE:6,
                FMTRECSIZE:6:'RIGHT',
                '  ', FMTTYPE:4,
                EOF:10,
                FLIMIT:11
                );
       END;

The header variables are set (MPEXHEADER3 is set to the empty string since the
header is only 2 lines long -- you should always specify all three variables
unless you are using MPEXFILESET, described below); the WRITELN indicates what
is to be output for each file.

Several other options are also available.  Saying


SELECT_764
SELECT

   FOR RFILE IN MPEXFILESETHEAD
     SELECT selectioncondition
     DO
       BEGIN
       statement;
       ...
       statement;
       END;

will do the "statement"s only for those files that match "selectioncondition".
For instance, MPEX's %LISTF mode 5 (which only outputs program file
information) specifies

   FOR RFILE IN MPEXFILESETHEAD
     SELECT ISPROG
     DO ...

to select only those files with code="PROG" or code="NMPRG".


MPEXFILESETHEAD_765
MPEXFILESETHEAD
Saying

   FOR RFILE IN MPEXFILESETHEAD

instead of

   FOR RFILE IN MPEXFILESETTOTAL

will cause MPEX not to print any group, account, or grand totals (of the number
of files and of the disc space).  Instead, you can specify your own things to
be done at every "group break" and "account break" by using "ONBREAKBEFORE" and
"ONBREAKAFTER" (with "ALREADYSORTED").

THE FULL SYNTAX OF A FLEXIBLE LISTF FORMAT FILE


FIRST_766
FIRST


PAGEHEAD_767
PAGEHEAD


ONBREAKBEFORE_768
ONBREAKBEFORE


ONBREAKAFTER_769
ONBREAKAFTER


FINALLY_770
FINALLY

   (* Comments -- may be inserted anywhere *)
   MPEXHEADER1 := "headerline1";
   MPEXHEADER2 := "headerline2";
   MPEXHEADER3 := "headerline3";
   other statements to do before any files are processed;
   FOR RFILE IN MPEXFILESET[HEAD|TOTAL]
     SELECT selectioncondition
     SORT|ALREADYSORTED (sortfields)
     FIRST
       BEGIN
       statements to do at the beginning of the fileset;
       END
     PAGEHEAD
       BEGIN
       statements to do at the beginning of each page of output;
       END
     ONBREAKBEFORE 1
       BEGIN
       statements to do at the beginning of each new account
         ("ONBREAKBEFORE 1" means "before breaking on sort item 1",
          which is the account if you use "ALREADYSORTED");
       END
     ONBREAKBEFORE 2
       BEGIN
       statements to do at the beginning of each new group
         (or whatever sort item 2 is, if you don't use "ALREADYSORTED");
       END
     DO
       BEGIN
       statements to do for each file;
       END
     ONBREAKAFTER 2
       BEGIN
       statements to do at the end of each group
         (or whatever sort item 2 is, if you don't use "ALREADYSORTED");
       END
     ONBREAKAFTER 1
       BEGIN
       statements to do at the end of each account
         (or whatever sort item 1 is, if you don't use "ALREADYSORTED");
       END
     FINALLY
       BEGIN
       statements to do at the end of the fileset;
       END;

You can specify as many or as few of the above clauses as you like -- put
together they can do some very powerful things.  A very simple example might
be:

   FOR RFILE IN MPEXFILESETHEAD
     DO
       BEGIN
       WRITELN (FILE:8, "  ", SECTORS:10, SAVABLESECTORS:10);
       END
     ONBREAKAFTER 2
       BEGIN
       WRITELN ("TOTAL SAVABLE DISC SPACE: ", TOTAL(2,SAVABLESECTORS));
       END;

For each file, this outputs the name, the number of sectors, and the number of
savable sectors (savable, that is, by an %ALTFILE ;XLTRIM).  After each group
is finished (ONBREAKAFTER 2), it writes the total savable disc space in the
entire group.  Note the expression


TOTAL_771
TOTAL

   TOTAL(2,SAVABLESECTORS)

TOTAL(2,x) returns the sum of x for all files in this group; TOTAL(1,x) returns
the sum of x for all files in this account; TOTAL(0,x) returns the sum of x for
all files in the fileset.  In general,

   TOTAL(n,x)

can be said to be the sum of all 'x'es since the last Nth level break; 'x' can
be any file attribute variable (however, 'x' can not be a user-defined variable
whose value is calculated in the "DO" section).  We could have done the same
thing without a TOTAL by saying:

   VAR SPACE: INTEGER;
   FOR RFILE IN MPEXFILESETHEAD
     ONBREAKBEFORE 2
       BEGIN
       SPACE:=0;
       END
     DO
       BEGIN
       WRITELN (FILE:8, "  ", SECTORS:10, SAVABLESECTORS:10);
       SPACE:=SPACE+SAVABLESECTORS;
       END
     ONBREAKAFTER 2
       BEGIN
       WRITELN ("TOTAL SAVABLE DISC SPACE: ", SPACE);
       END;

This explicitly initializes a tally variable before each group starts,
increments it for each file, and outputs it after the entire group is done.

A useful idiom, incidentally, is TOTAL(n,1).  This stands for the total number
of files since the last n-level break -- TOTAL(2,1) is the total number of
files in the group, TOTAL(1,1) is the total number of files in the account, and
TOTAL(0,1) is the total number of files in the fileset.

Another structure you might want to use is:


MPEXFILESET_772
MPEXFILESET

   FOR RFILE IN MPEXFILESET
     ...

(as opposed to "FOR RFILE IN MPEXFILESETHEAD" or "FOR RFILE IN
MPEXFILESETTOTAL").  This simply tells MPEX not to print any headers (global,
group, or account) and not to print any totals, but only do those things that
you specify in the FOR statement.  For instance,

   %LISTF fileset, FILENAME

(which simply lists the fully-qualified names of the files in the given
fileset) is implemented using the file FILENAME.LISTF.VESOFT, which says:

   FOR RFILE IN MPEXFILESET
     DO WRITELN (FULLNAME);

You don't want any headers or totals in %LISTF ,FILENAME -- you just want the
fully-qualified file names; this is what "FOR RFILE IN MPEXFILESET" is useful
for.

Of course, even if you use "FOR RFILE IN MPEXFILESET", you can still print your
own headers (using FIRST, ONBREAKBEFORE, ONBREAKAFTER, and FINALLY).  It's just
that you'd have to specify the headers that you want explicitly.  For instance,
saying


ALREADYSORTED_773
ALREADYSORTED

   FOR RFILE IN MPEXFILESET
     ALREADYSORTED (ACCOUNT:8, GROUP:8)
     ONBREAKBEFORE 1
       WRITELN ("ACCOUNT = ", ACCOUNT)
     ONBREAKBEFORE 2
       WRITELN ("GROUP = ", GROUP)
     DO
       WRITELN ("FILE = ", FILE);

will output "ACCOUNT = accountname" before every account's files and "GROUP =
groupname" before every group's file.

Note the "ALREADYSORTED (ACCOUNT:8, GROUP:8)" -- this is necessary to tell MPEX
that you should expect the files to be sorted in account and group order.  With
"FOR RFILE IN MPEXFILESETHEAD" and "FOR RFILE IN MPEXFILESETTOTAL" you don't
have to do this, but for "FOR RFILE IN MPEXFILESET" you must specify the
"ALREADYSORTED" clause if you'll be using ONBREAKBEFORE, ONBREAKAFTER, and/or
TOTAL.

By default, all %LISTF output prints the files in sorted order (by account,
then by group, then by file).  You can specify your own sort sequence by
saying:


SORT_774
SORT

   FOR RFILE IN MPEXFILESET
     SORT (field1, field2, ...  fieldN)
     DO ...

(of course, you can also specify SELECT, FIRST, FINALLY, and [especially
useful] ONBREAKBEFORE and ONBREAKAFTER).  Each fieldX parameter indicates what
you want to sort it on (the highest-precedence things first).  (Note: for SORT
to work, you must use MPEXFILESET, not MPEXFILESETHEAD or MPEXFILESETTOTAL.)
For instance, saying

   FOR RFILE IN MPEXFILESET
     SORT (ACCDATE, MODDATE)
     DO ...

will sort all the files in the fileset by their last access date (ACCDATE), and
within that (for all files with the same last access date) by last modify date.
Saying

   FOR RFILE IN MPEXFILESET
     SORT (ACCOUNT:8, SECTORS)
     DO ...

will sort first by the account and then by the file's disc space.  Note that we
said "ACCOUNT:8" -- the 8 is the maximum length of the account name.  Whenever
you sort by a STRING, you must specify the maximum length of the string field
(otherwise you'll get an error message).  You can also append a ":'DESC'" to
any of the fields to indicate a sort in DESCending order:

   FOR RFILE IN MPEXFILESET
     SORT (ACCOUNT:8, SECTORS:'DESC')

will sort by account, and within each account, in descending order by the
number of sectors (i.e.  the biggest files first).

When you do your own SORTing, the ONBREAKBEFORE, ONBREAKAFTER, and TOTAL
constructs are especially useful.  In general, an

   ONBREAKBEFORE n
     BEGIN
     ...
     END

will be executed before the Nth field in the SORT list changes -- thus, in the
SORT (ACCOUNT:8, SECTORS:'DESC') example, any ONBREAKBEFORE 1 will be executed
before the start of each new account.

An ONBREAKAFTER N will similarly be executed after the Nth field in the SORT
list changes.  TOTAL(n,x) will sum all the values of x since the last change in
the Nth field.

One more example that uses ONBREAKAFTER, SORT, and TOTAL:

      FOR RFILE IN MPEXFILESET
        SORT (ACCOUNT:8, CREATOR:8)
        ONBREAKAFTER 2
          WRITELN (CREATOR, '.', ACCOUNT, ' created ',
                   TOTAL(2,1), ' files, ',
                   TOTAL(2,SECTORS), ' sectors');

This sorts all the files in the fileset by their account and creator ID; then,
for each creator (level-2 break), it outputs the number of files created by
that user (TOTAL(2,1)) and the number of sectors those files occupy
(TOTAL(2,SECTORS)).  Since only an ONBREAKAFTER 2 clause was specified, only
the creator-level totals will be output; no information will be output for each
file, nor will any account or grand totals be printed.


VESOFTSORTFILESIZE_775
VESOFTSORTFILESIZE
One final note on using SORT (...) in a flexible listf file: if the number of
files to be %LISTFed is very large (more than 10000 files), you may get an
error message regarding the file SORTWRIT.PUB.VESOFT.  If this occurs, you can
set the variable VESOFTSORTFILESIZE to the number of files you expect to be
listed.

So, there it is -- the way for you to write your own flexible %LISTF files.  As
you can see, you can do arbitrary sorts, totals, and formatted outputs; you can
define %LISTF modes even more complicated (and useful) than the ones we've
predefined.

Perhaps the best way to learn how to write flexible %LISTF files is by looking
at the VESOFT-supplied files in the LISTF.VESOFT group.  The only thing we can
warn you about is that some of those files use additional, undocumented
constructs that we may not be prepared to release yet to the user community at
large -- however, most of the stuff that the LISTF.VESOFT files do can as
easily be done by your own flexible %LISTF files.


_LISTJOB_776
%LISTJOB


_LISTJOB_777
%LISTJOB


_SHOWJOB_778
%SHOWJOB

Syntax:   %LISTJOB [userset]
                   [;NOPROC]
                   [;NOSORT]
                   [;SUBMIT]

Examples: %LISTJOB;SUBMIT

JOB#     STATE    DEV   INTRODUCED  Q PROGRAM  LOGON

#S27     EXEC     20    TUE  2:28P    MAIN     OPERATOR.SYS,OPERATOR
#S127    EXEC     38         9:44A    QEDIT    CHUCK,MANAGER.TECH,CHUCK
#S116    EXEC     33         7:17A    MAIN     RON,MANAGER.TECH,RON
#S117    EXEC     35         7:37A             RON,same

#J555    EXEC   o766    WED 12:16P  b+MAIN     BACKG,MANAGER.VESOFT,BACKG
                                                 #s27, operator.sys
#J601    WAIT D1        THU 10:52A             TEST,MANAGER.TECH,CHUCK
                                                 #s88, chuck,manager.tech

#J880    SCHED   HI     SAT 12:01A  01/22/94   SCHEDULR,MANAGER.SYS,PUB
                                                 #j567, schedulr,manager.sys

#A6     SCHED +              1:30A   -MTWRF-   BACKUP,MANAGER.SYS
#A4     SCHED +             12:35A   S-----A   DISCLEAN,same
#A8     SCHED + WHENEVER (HPDATE=1)            REPORT,same
#A11    SCHED           FRI 10:00A  94/09/16   TESTSCHD,same
#A1     SCHED +             12:10A   SMTWRFA   GETDFREE,MANAGER.TECH
#A2     SCHED +             12:15A   -MTWRF-   DAILY,MGR.XPRESS
#A7     SCHED + WHENEVER BETWEEN(HPDAY,2,6)...  REMOTE,USER.XPRESS

JOBFENCE = 6; JLIMIT = 3; SLIMIT = 33

The %LISTJOB command is similar to the MPE :SHOWJOB command, but displays
additional information and allows for selection based upon a userset.

The key features of this command are:

   * Name and queue of the currently running process.  If there is more than
     one process running, the first process on the process tree will be listed
     with a "+" character to indicate additional processes are active.

   * The MPE group name is displayed for each user.

   * The output is sorted by job type (sessions first, then jobs), account,
     user, and finally the job or session number.

   * Selection based upon MPEX jobsets.

Note that fields that have trivial values -- such as the STATE when it's EXEC,
the LDEV for jobs, the INTRO date when it's today, etc.  -- are not displayed.

The ;NOPROC keyword disables the display of the currently executing process for
each job or session.

The ;NOSORT keyword disables the sort step prior to display.  Without the sort,
multiple occurrences of the same user, group, and account may not be displayed
as "Sessionname,same" as shown above.

The ;SUBMIT keyword, when specified, displays additional information about each
JOB.  With this keyword, an additional line indicating the original submitter
of the job will be displayed.

At the end of the listing, STREAMX scheduled jobs are displayed as follows:

   * For ordinary jobs that do not repeat or have a particular condition to be
     streamed are shown with the scheduled date & time to submit in the
     INTRODUCED and PROGRAM columns.

   * Jobs that repeat are indicated with a "+" character to the right of the
     word "SCHED".

   * If the job is to be submitted when a particular condition occurs, the
     conditional expression for that job will be displayed.  If the condition
     is too long to display in the field, then it is truncated and "..." is
     printed to show that it is too long to display.

   * For jobs that repeat on specific days, the days that the job repeats is
     shown in the PROGRAM column.

This is essentially the same format as the %SHOWJOB command, and shows the same
information as the %SEC SHOWSCHED command.  %SEC SHOWSCHED, however, will
display the entire condition under which a job will be submitted.

Syntax:   %LISTREDO [abscmdnum1[/abscmdnum2]]  [;OUT=outfile]
                    [-relcmdnum[/-relcmdnum2]]  [;REL|ABS|UNN]
                    [["][@]string["]         ]

Examples: %LISTREDO
          %LISTREDO 10/20
          %LISTREDO START=10; END=20
                    (* for compatibility with MPE/iX *)
          %LISTREDO -30;REL
          %LISTREDO RUN
          %LISTREDO @MYFILE

          %FILE LP;DEV=LP
          %LISTREDO;OUT=*LP;UNN

%LISTREDO displays those commands that you entered into MPEX and that have been
saved in the MPEX command history.

%DO, %LISTREDO, and %REDO are all intimately related, and are discussed in full
detail under the %REDO command in this manual.


_MANY_779
%MANY

Syntax:   %MANY delimiter mpexcommand [delimiter ...  ]

Examples: %MANY DATAFILEDATAFILEPROGFILE
          %MANY %REPEAT  %BUILD FILE!N  %FORNUM N=1,10

The %MANY command lets you specify several MPEX commands on one line; for
instance,

     %MANY %REPEAT %RUN MYPROG;INFO="!MPEXCURRENTFILE" %FORFILES A@

will execute the given %REPEAT ...  %FORFILES loop just as if you'd typed

   %REPEAT
   %  RUN MYPROG;INFO="!MPEXCURRENTFILE"
   %FORFILES A@

This can be especially useful for "$" commands (to submit a job stream that
executes several commands) and for :RUN MPEX;INFO="...".

Note that the commands are delimited by the first character in the %MANY
command's parameter list -- the character "%" was used above, but if you wanted
to, you could have used something else, e.g.

     %$MANY ^REPEAT ^RUN MYPROG;INFO="!MPEXCURRENTFILE" ^FORFILES A@

Just make sure you use a character that doesn't occur in any of the commands
you are going to enter!


_MPEXSTORE_780
%MPEXSTORE

Syntax:   %MPEXSTORE fileset; storeparms

Examples: %MPEXSTORE @.@.@-@.@.SYS-@.@.VESOFT &
                     (ACCDATE<TODAY-90 and NOT ISPRIV);*T;SHOW

The MPE :STORE command can already handle filesets -- however, its filesets are
not nearly as flexible as MPEX filesets.  In particular:

   * It doesn't have selection criteria such as CODE,SECTORS,CREATOR, etc.  For
     instance, you can't store all the files that haven't been accessed in 90
     days EXCEPT FOR databases -- :STORE can't select by filecode.

The %MPEXSTORE command lets you use the full power of MPEX filesets with MPE
:STORE.  For instance, the command

   %MPEXSTORE @.@.@-@.@.SYS-@.@.VESOFT &
                (ACCDATE<TODAY-90 and NOT ISPRIV);*T;SHOW

will store all files that haven't been accessed in 90 days EXCEPT:

   * databases (ISPRIV),

   * files in the SYS account (-@.@.SYS), and

   * files in the VESOFT account (-@.@.VESOFT).

Of course, all the other fileset features and selection criteria are available,
too -- you can store all the files created by a particular user, store all the
files except for files with code PROG and USL (since in the event of failure
they could easily be regenerated), etc.

This command works by doing %listf ,FILENAME to write the fully qualified names
of all the files in the fileset to a disc file; then, it uses the disc file as
an indirect file for MPE :STORE.  For large filesets, this means that it might
take some time for this command to start up (since it has to go through the
entire fileset before doing the :STORE).  Please be patient...


_NEWLINK_781
%NEWLINK

Syntax:   %NEWLINK linkfileset, targetfileset

Examples: %NEWLINK MYLINK, REALFILE
          %NEWLINK WORK, /DEVELOP/PUB/source/c
          %NEWLINK =.TEST, @.PROD

The %NEWLINK command allows you to create a symbolic link to another file or
directory.  Since symbolic link files are a POSIX related feature, this command
is only available on machines that support POSIX.

Symbolic link files are files that "point" to other files, somewhat like a
permanent file equation.  When a link file is referenced in a command or
program, the file that the link points to is actually opened.  Our %LISTF ,2
listf mode shows the target of a link file as follows:

%LISTF ./A@/,2

PATH= /DOC/WORK/

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

A09     /         ==>  NEWFILE
A16                link /DOC/WORK/A09/NEWFILE         16  1  *

PATH= /DOC/WORK/A09/

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

NEWFILE            80B  FA     1420    1420  16      448  *  *

In this example, the file A09 is a DIRECTORY containing the file NEWFILE.  The
file A16 is LINKED to NEWFILE, so if you were to reference A16 in your command
(such as :VI A16 to invoke the VI editor), then the file /DOC/WORK/A09/NEWFILE
will be opened as the actual work file.

This command is quite a bit different than other commands that have a "source"
and "target" fileset.  For this command, the files in the linkfileset are based
upon files in the targetfileset, rather than the target files being based upon
the source files.  The third example above shows how to create a link file in
the TEST group for each file that exists in the PROD group.  This would allow
you to perform a test against "live data" without having to move files from one
location to another.

In order to remove a symbolic link file, the command %PURGELINK must be used
instead of the regular %PURGE command.  (see the %PURGELINK command for
details)


_NOMSG_782
%NOMSG

Syntax:   %NOMSG command

Examples: %NOMSG INPUT ANSWER; PROMPT="OK to continue? "; WAIT=5

          %REPEAT
          ...
          %NOMSG FORFILES A@.SOURCE

Saying

   %NOMSG command

does the same thing as saying

   %command

(without the NOMSG) except that %NOMSG inhibits the printing of any MPE CI or
file system errors associated with the command.

The CIERROR and FSERROR JCWs are still set; if the command encounters a fatal
error and no %CONTINUE is in effect, the command file or UDC will still be
flushed.  The only difference is that no error message will be printed.

This can be quite useful in cases where you expect an error to occur, and don't
want to burden the user with an irrelevant warning or error message.  For
instance, if you have a command file that uses a particular work file and you
want to make sure the file doesn't already exist, you might say:

   %NOMSG PURGE WORKFILE;YES

This way, the "FILE NOT FOUND, NO PURGE DONE" warning will not be printed out
if WORKFILE doesn't exist.  Remember that you can still check to see if an
error occurred by looking at the CIERROR and FSERROR variables.


_OPTION_783
%OPTION

Syntax:   %OPTION [LIST]
                  [NOLIST]
                  [RECURSION]
                  [NORECURSION]

Examples: %OPTION LIST
          %OPTION RECURSION

MPE/iX lets you have an OPTION line not just at the beginning of a command file
or a UDC, but also anywhere inside one.  The only four options available on
this OPTION command are:

   * LIST and NOLIST, which turn on or off echoing of the remaining commands in
     this command file.

   * RECURSION, which makes MPEX search for UDCs starting with the very
     beginning of the UDC directory (rather than just starting with the
     currently-executing UDC) -- this lets a UDC call itself recursively
     (either directly or indirectly, e.g.  when UDC A calls UDC B which in turn
     calls A).

   * NORECURSION, which turns off OPTION RECURSION and allows UDCs to only call
     those UDCs which come after them in the UDC directory.  (This is the
     default state).

OPTION LIST can be useful when you're debugging a UDC and want to check which
commands are being executed; however, the MPEXCMDTRACE JCW (documented
elsewhere in this manual) is probably more useful for this purpose.  OPTION
RECURSION could be convenient in some cases, but you might just want to use
command files (which can always be used recursively) instead.


_PAUSE_784
%PAUSE

Syntax:   %PAUSE numseconds

Examples: %PAUSE 300

Suspends MPEX for the given number of seconds.


_PAUSEJOB_785
%PAUSEJOB

Syntax:   %PAUSEJOB "[time|booleanexpression]" , userset
          [;VERIFY|NOVERIFY|QUIET]
          [;scheduleparms]
          [;CHECKEVERY=minutes]

          %SHOWPAUSED

Examples: %PAUSEJOB "5:30PM", #J123
          %PAUSEJOB "11:00PM", COMPILE,@.@; NOVERIFY
          %PAUSEJOB "JSCOUNT('@,REPORT.@&EXEC')<=3", REPORT,@.@
          %PAUSEJOB , #J987; IN=0,0,120

The %PAUSEJOB command allows you to SUSPEND (via the :BREAKJOB command) a
particular job or jobset (using VESOFT usersets -- see the usersets section of
the SECURITY User Manual for details), and have MPEX automatically RESUME the
job at a specified future time, or when a given expression becomes true.

The syntax for %PAUSEJOB is quite similar to %ALARM (documented earlier in this
manual).  In fact, you must have the ALARM task running under the BACKG job in
order for %PAUSEJOB to be able to RESUME the job later (%PAUSEJOB actually sets
a special type of alarm to later :RESUMEJOB the suspended job).  For this
reason, if you issue a %PAUSEJOB command and the BACKG job is not already
running, MPEX will attempt to start it for you.  For more information on the
BACKG facility, please see the documentation for the %BACKG command, earlier in
this manual.


AT__786
AT=


DAY__787
DAY=


DATE__788
DATE=


IN__789
IN=
You may tell %PAUSEJOB to RESUME the suspended job:

   * at a particular future time (e.g.  "5:30 PM");

   * when a particular boolean expression becomes true (e.g.
     "JSCOUNT('COMPILE,@.@')<=3"); or

   * using the MPE :STREAM-style scheduling parameters ;AT=, ;DAY=, ;DATE=, and
     ;IN= (e.g.  ";IN=0,0,5" or ";DATE=11/05/91;AT=9:00").


VERIFY_790
VERIFY


NOVERIFY_791
NOVERIFY


QUIET_792
QUIET
If you specify a jobset (rather than a single job), %PAUSEJOB will list all of
the jobs that will be affected and ask

   OK to process these jobs (y/n)?

If you don't want to be asked, use the ;NOVERIFY keyword.  If you don't even
want %PAUSEJOB to list the jobs that it processes, use the ;QUIET keyword
(which implies ;NOVERIFY).

PERFORMANCE CONSIDERATIONS (;CHECKEVERY=)


CHECKEVERY__793
CHECKEVERY=
By default, the ALARM background task wakes up once per minute to see if any of
the %PAUSEJOB conditions have been met (i.e., the "logical expression" returns
TRUE).  If you set a %PAUSEJOB alarm based on an expression that will use a lot
of system resources (CPU, disc I/Os, etc.) to evaluate, you may want to check
that particular alarm less frequently.

When you enter a %PAUSEJOB command, simply append the ;CHECKEVERY= keyword to
tell the ALARM background task how many intervals to skip between tests.  For
example,

   %PAUSEJOB "JSCOUNT('COMPILE,@.@&EXEC')=0", #J115; CHECKEVERY=10

This means ":BREAKJOB #J115, and when there are no more jobs executing that
logged on with a jobname of COMPILE, :RESUMEJOB #J115.  Since the default pause
time is 1 minute, this will wait 10 minutes between tests.  Please see the
documentation on the %ALARM and %BACKG commands earlier in this manual for more
details.

VIEWING "PAUSED" JOBS (%SHOWPAUSED)


_SHOWPAUSED_794
%SHOWPAUSED
To find out what %PAUSEJOB commands still have :RESUMEJOB alarms pending for
them, use the %SHOWPAUSED command.  For each "paused" job that is still
suspended, you will be shown the job number, the intro time, the "will resume"
time (unless the %PAUSEJOB was set to resume based on a logical expression),
and the job name.


_PRINT_795
%PRINT

Syntax:   %PRINT [fileset|(file-eq-parms)]
          [;BUF]
          [;COPY[ACCESS]]                                  (NEW)
          [;FORMAT= formatstring]
          [;HIGHLIGHT]                                     (NEW)
          [;KEEPAMDATES]
          [;NOFILEPAGEBREAK]
          [;NONUMRECOGNIZE] [;UNN|NUM]
          [;OLD|OLDANY|OLDTEMP]
          [;OUT= outfile|(file-eq-parms)]
          [;PAGE= pagesize] [;PAGEHEAD]
          [;PAGEHEAD]
          [;SEARCH= expression]
            [;ALLFILENAMES]
            [;CONTEXT= [numlines1|exp1],[numlines2|exp2]]
            [;MAX= numlines]
            [;PREV= expression]
          [;START= startrecnum] [;END=endrecnum]
          [;WAIT=[[+|-]numseconds]]                        (NEW)

Examples: %FILE LP;DEV=LP;CCTL
          %PRINT AP@.SOURCE(CODE="EDTCT");NUM;KEEPAMDATES &
                 ;OUT=*LP;PAGEHEAD
          %PRINT MYFILE;START=100;END=150;NUM
          %PRINT PROGFILE;FORMAT=STRWRITE(R:'GARBAGE')

          %PRINT @.SOURCE;SEARCH="CUSTNO" or "CUSTNUM" or "CUSTNAME"
          %PRINT @.SOURCE &
             ;SEARCH=("FOO" and "BAR") or ("XYZ" and NOT "ABC")
          %PRINT @.DOC;SEARCH=CASELESS "DEBUG"
          %PRINT @.SOURCE;SEARCH=DELIM "CUST"
          %PRINT @.SOURCE;SEARCH="FNAME" &
             ;PREV="PROCEDURE" OR "FUNCTION"
          %PRINT @.SOURCE;SEARCH=CL"PAR-ONE" &
             ;CONTEXT="PERFORM","END-PERFORM"

The %PRINT command lets you conveniently output filesets (or individual files)
to the terminal, to the printer, or to some external file.  Major features
include:

   * You can print entire filesets (temporary or permanent), e.g.

        %FILE LP;DEV=LP
        %PRINT @.SOURCE(CODE="EDTCT"); NUM; OUT=*LP; PAGEHEAD

     This will print all the files in the SOURCE group that are EDITOR /SET
     FORMAT=COBOL files (CODE="EDTCT") with line numbers to the line printer.
     This is more convenient than
        %EDIT @.SOURCE (CODE="EDTCT"), LIST ALL,OFFLINE
     because it doesn't print any of those pesky one-page /VERIFY ALLs that
     EDITOR is so fond of.  (The %PRINT command is also faster.)


Using_PRINT_OUT__without_issuing_a_file_equation_796
Using PRINT;OUT= without issuing a file-equation
   * When specifying the file to be printed or the ;OUT= file, you can specify
     not just a filename, but an entire file equation (except for the word
     "FILE") -- you can even use the special extensions described under VEFOPEN
     in Appendix).  Thus you can say

        %PRINT MYFILE;OUT=(LP;DEV=LP,5,2;ENV=MYENV.HPENV.SYS)
        or
        %PRINT (XFILE,OLD;EXC);SEARCH=...

     Note that the "filename" MUST be enclosed within parenthesis.  This
     indicates to MPEX that the keywords that follow (DEV, REC, etc.) are for
     the FILE to be processed or used as output and not as parameters to the
     command itself.

     This essentially saves you from having to set (and :RESET) a special
     :FILE-equation; however, it is especially useful with our STDLIST function
     (see Appendix).  A quick example:

        %PRINT (![STDLIST('RUN MYPROG')]); &
               SEARCH="ERROR"; CONTEXT=,2; &
               FORMAT=STRCHANGE(R,"ERROR","*****ERROR*****   ")

     This runs the program MYPROG and passes its output to the %PRINT command,
     which prints all of the lines that contain the string "ERROR" (+ the 2
     following lines), changing "ERROR" to "*****ERROR*****   " for emphasis!

   * When you're outputting to the terminal, the display will pause every 23
     (or however many you specify) lines -- when you press [RETURN], it will
     resume printing.

   * You may (by specifying the ;NUM keyword) see the line number of each line
     output -- this is either the absolute record number or, if the file is
     numbered, the true line number from the file.

   * You can indicate (with ;START= and ;END=) which records of the file you
     want to output.

For instance, if you say

   %PRINT MYFILE; START=-8; NUM

it will display -- with line numbers -- the last 8 lines of the file:

    99           PROC (CAPS)
   100         ELSE IF MINUS'CAPS <> 0D THEN
   101.1         PROC (DNOT (MINUS'CAPS))
   101.5       ELSE
   102           PROC (-1D);
   110         END;
   111       END;
   113     END.

If you had said

   %PRINT MYFILE; START=10; END=60; NUM

it would have displayed the 10th through the 60th line of the file; however,
since this would fill up more than one terminal screen, it would pause every
23rd line and say, for example:

   31                      "or all - capabilities" TO'TERMINAL
   32         ELSE IF CAPS <> 0D THEN
   (33/97) Continue (Yes/No/Quit/Dontask)?

At this point, you could:

   * Press [RETURN] or type Y (for "Yes") to see the next 23 lines.

   * Type N (for "No") to stop printing this file.

   * Enter a positive integer (e.g.  50) to continue printing the file starting
     with record number 50 (counting from 1).

   * Enter an integer prefixed by a + (e.g.  +5) to continue printing the file
     starting with record number 38 (=33+5, where 33 is the number printed
     before the "/" in the "Continue?" line).

   * Enter an integer prefixed by a - (e.g.  -10) to continue printing the file
     starting with record number 23 (=33-10, where 33 is the number printed
     before the "/" in the "Continue?" line).

   * Press Q (for "Quit") to stop printing all files in the current fileset.

   * Press D (for "Dontask") to print the rest of this file and all of the
     files in the current fileset, without stopping for a "Continue?" prompt
     again.

(The first number in the parentheses -- 33 -- is the current record number; the
second number -- 97 -- is the total number of records in the file.)

%PRINT keywords


BUF_797
BUF


Stack_overflows_in__PRINT_798
Stack overflows in %PRINT
   * ;BUF -- used to avoid stack overflow errors.  By default, the %PRINT
     command reads files NOBUF, which makes fileset searches more efficient.
     Unfortunately, it also uses more stack space; it is possible (though
     unlikely) that if your ;SEARCH= and ;PREV= selection conditions are
     complicated enough, you will get a stack overflow.

     If this happens, just specify ";BUF" on your %PRINT command, e.g.

        %PRINT @.SOURCE;SEARCH=...;BUF

     This will tell MPEX to do buffered reads, which will use less stack space
     but will also be slower.


COPYACCESS_799
COPYACCESS
   * ;COPY[ACCESS] -- uses non-destructive reads for message files.  MPEX's
     %PRINT command uses ordinary intrinsics to read a file.  In the case of a
     message file, records that have been read from the file are deleted --
     nothing special, this is exactly what is supposed to happen when reading a
     message file.  However, when you are searching a fileset that contains a
     message file, reading (and therefore emptying) a message file may have
     disastrous side effects on your production environment.  Another side
     effect of reading a message file is that if the file is empty to begin
     with, the read will wait or "hang" until someone actually WRITES to the
     file.  When this happens, MPEX appears to "hang" and you have to press
     [BREAK] and type :ABORT to exit the program.

     When you use ;COPYACCESS (which may be abbreviated to just COPY), MPEX
     will use a special mode when reading message files that preserves the
     contents of the file and will not "hang" if the file is empty.


FORMAT_800
FORMAT


R_801
R
   * ;FORMAT= lets you tell %PRINT not to output the actual record from the
     file, but rather to output some function of the record.  Here are some
     examples and their explanations:

     %PRINT ...;FORMAT=R[0:10]

        Displays just the first 10 characters of each record.

     %PRINT ...;FORMAT=STRWRITE(R:'GARBAGE')

        replaces unprintable characters with a ".".

     %PRINT ...;FORMAT=TOKEN(REMTOKEN(R,'AN'),'AN')

        displays just the second "token" of each record (see the discussion of
        TOKEN and REMTOKEN in Appendix for more details).

The ;FORMAT= parameter can be any expression whose result is a string.


HIGHLIGHT_802
HIGHLIGHT
   * ;HIGHLIGHT will display "-----Printing: filename" in inverse video.  This
     is most useful when printing a fileset using ";search=" and displaying
     only a few lines from each file.  When ;HIGHLIGHT is specified on the
     print command, the filename will be printed in inverse video (if you are
     using an HP terminal or emulator).  This makes it easy to distinguish the
     filename from the text of each file being printed.


KEEPAMDATES_803
KEEPAMDATES
   * ;KEEPAMDATES -- indicates that the files' last Access and Modification
     dates should not be changed as the files are printed or searched; this is
     really useful if you want to print or search a whole fileset but still
     want all those files to be eligible for archival if they haven't been
     accessed in a long time.


MPEXPRINTKEEPAMDATES_804
MPEXPRINTKEEPAMDATES
     If you say :SETJCW MPEXPRINTKEEPAMDATES=1 in your MPEXMGR.PUB.VESOFT file,
     the ;KEEPAMDATES keyword will always be in effect for the %PRINT command.
     (see also the discussion on MPEXDEFAULTxxx variables).


NOFILEPAGEBREAK_805
NOFILEPAGEBREAK
   * ;NOFILEPAGEBREAK -- tells MPEX not to do a page break after each file it
     prints.  This is useful if you're doing a %PRINT ;SEARCH= and are
     therefore printing only one or two lines from each file; you don't want to
     have a page break every one or two lines.


NONUMRECOGNIZE_806
NONUMRECOGNIZE
   * ;NONUMRECOGNIZE -- indicates that %PRINT should print the full text of the
     file despite the fact that the last 8 characters of the first line are
     digits.  If you don't specify this keyword, %PRINT will think that the
     file is a numbered file, and treat the last 8 digits as the line number;
     this is usually the right thing to do, but for files that contain actual
     numeric data in the last 8 columns, ;NONUMRECOGNIZE is the way to go.


UNN_807
UNN
   * ;UNN -- indicates that output should not contain record numbers (whether
     or not the file has internal line numbers).  This is ordinarily the
     default, but if you have set a VESOFTDEFAULTPRINT variable with ";NUM",
     then this will override the variable for this command only.


NUM_808
NUM
   * ;NUM -- indicates that output should contain either line numbers (if the
     file is numbered) or record numbers (if the file is unnumbered).  This is
     most useful when printing source files that are kept numbered (such as
     EDTCT files).  See the section on ;SEARCH= for another useful facet of
     this keyword.


OLD_809
OLD


OLDANY_810
OLDANY


OLDTEMP_811
OLDTEMP
   * ;OLD means "process permanent files only."
     ;OLDTEMP means "process temporary files only."
     ;OLDANY means "for each file in the fileset, first look for the file as a
     temporary file and then, if none exists, as a permanent file".

     What is the default? Well, if you specify a single file (i.e.  a filename
     with no wildcards, no indirect file, no + or -, and no selection
     condition), the default is ;OLDANY (first TEMP, the PERM); if you specify
     a fileset, the default is ;OLD (PERM files only).


Temporary_files_and_the__PRINT_command_812
Temporary files and the %PRINT command
Note: for compatibility with MPE/iX's :PRINT command, if you type "%:PRINT
filename" or "%PRINT filename", MPEX will look first for a temporary file and
then, only if it doesn't find one, a permanent file.  However, a %PRINT fileset
command will NOT print any temporary files because this is a fileset-handling
command and we don't want to surprise you by  printing a whole bunch of
permanent files and one temporary file that happens to have the same name as a
permanent file.


OUT_813
OUT
   * ;OUT=filename -- indicates that output is to go to the specified file,
     such as the line printer; for example, to output to the line printer, you
     might do a ":FILE LP;DEV=LP" and then a "%PRINT fileset;OUT=*LP".
     (Naturally, if this option is selected, you won't be prompted with
     "(xx/yy) Continue?" every so many lines.)

   * ;OUT=(file-eq-parms) -- indicates that output is to go to the file or
     device specified in the file-eq-parms without using a :FILE equation.  For
     example, %PRINT fileset;OUT=(LP;DEV=LP) will perform the same print as
     above (sending the output to the printer) without actually setting a file
     equation.


PAGE_814
PAGE
   * ;PAGE=pagesize -- indicates how many lines to print before prompting with
     "Continue (Yes/No/Quit/Dontask)?".

     The default is 23 when outputting to the terminal, 60 when outputting to
     the printer (no prompt in this case).


PAGEHEAD_815
PAGEHEAD
   * ;PAGEHEAD -- indicates that page headers (including the name of the file,
     the date and time, and the page number) are to be output to the ;OUT=
     file.  Useful when the ;OUT= file is the line printer.  If you use this
     option to print to the line printer, you should specify ;CCTL on your
     :FILE-equation for your ;OUT= file (:FILE LP;DEV=LP;CCTL).

     Default is that no page headers are to be output -- this is for
     compatibility with MPE/iX, although it's admittedly not very nice.


SEARCH_816
SEARCH
   * ;SEARCH=searchstring -- restricts output to only those lines containing
     the search string (or search expression).  This is perhaps the most
     powerful aspect of the print command and is documented in greater detail
     below.

     The following %PRINT keywords are useful only when ;SEARCH= has been
     specified:


ALLFILENAMES_817
ALLFILENAMES
     - ;ALLFILENAMES -- display all filenames as files are searched.
       Ordinarily, when using ;SEARCH=, MPEX will not display the name of each
       file being searched unless the file contains the search string.
       Specifying ;ALLFILENAMES causes MPEX to print each file as it is
       searched, regardless of whether or not the file contains the search
       string.  This is useful if you want to watch the progress of the command
       on a very large fileset when only a few files contains the search
       string.


PREV__818
PREV=
     - ;PREV=prevsearchstring -- searches backwards for a previous occurrence
       of a different search string.

       Let's say that you want to look through your programs for all
       occurrences of a particular variable.  Chances are that you don't just
       want to see the lines that mention the variable but that you also want
       to know in which procedure or function (in PASCAL terminology) the
       variable is referenced.

       For example, to see both the line that contains the word "CUSTNUM" and
       the last prior occurrence of the line that contains "PROCEDURE" or
       "FUNCTION", the following command will do exactly that:

       %PRINT @.SOURCE;SEARCH="CUSTNUM";PREV="PROCEDURE" or "FUNCTION";NUM
       -----Printing MYPROG.SOURCE
          11.5   PROCEDURE ERRORPROC (VAR F: INTEGER;
          15       WRITELN (CUSTNUM:10, ' NOT FOUND!');
         922     FUNCTION COPYREC (VAR FILE: TSTRING): BOOLEAN;
         939       IF CUSTNUM<>'XXX' THEN
         992.44    CUSTNUM:='';
         ...

       As MPEX reads each record from the SOURCE group files, it checks if the
       record contains PROCEDURE or FUNCTION; if it does, MPEX doesn't print
       the record but rather saves it away.  Then, when MPEX actually finds a
       record that refers to CUSTNUM, it prints both the saved
       PROCEDURE/FUNCTION record and the CUSTNUM record.


CONTEXT_819
CONTEXT
     - ;CONTEXT=[startrec|startstring],[endrec|endstring] displays the line
       being searched for and the lines surrounding the search string.  For
       example:

       %PRINT MYFILE;SEARCH="CUSTNO" or "CUSTNUM";CONTEXT=-1,+2

       will print 1 line before and 2 lines after each line that contains
       "CUSTNO" or "CUSTNUM".

       But wait -- there's more! What if you don't want to show a fixed number
       of lines before or after, but show the entire logical unit that contains
       the line found by ;SEARCH=, no matter how large it is? Here's an example
       of how you might do this:

       %PRINT MYFILE;SEARCH="CUSTNO" or "CUSTNUM";&
              CONTEXT=("PROCEDURE" or "FUNCTION"), (R[0:3]="END")

       Here, MPEX will find all the lines containing the string "CUSTNO" or
       "CUSTNUM", and then print all the lines from the immediately preceding
       line that contains "PROCEDURE" or "FUNCTION" and until the immediately
       following line that contains "END" as its first three characters.  This
       is, of course, appropriate for PASCAL programs; however, other languages
       and files will have similar ;CONTEXT= strings.  For instance, to display
       all the UDCs in a particular file that :RUN a particular program, you
       can say:

       %PRINT UDC1;SEARCH="RUN PRG";CONTEXT=(R[0:1]="*"),(R[0:1]="*")

       the ;CONTEXT= in this example indicates that all lines surrounding the
       RUN command, from the preceding line with an "*" in column 1 to the
       following line with an "*" in column 1 are to be printed.

       The general syntax of the ;CONTEXT= keyword is thus:

       ;CONTEXT=[-numlines1],[+numlines2]
                [exp1]      ,[exp2]

       The number or expression before the comma indicates which lines before
       the line containing the found string are printed; the number or
       expression after the comma indicates which lines after that line are
       printed.

       As you may have noticed, we've used both strings (e.g.
       ;CONTEXT="PROCEDURE") and logical expressions (e.g.
       ;CONTEXT=R[0:1]="*") in our examples.  This corresponds to the way
       ;SEARCH= and ;PREV= work -- they can take either strings (which mean
       "search for this string") or expressions (which mean "search for lines
       for which this expression is true").  A string in a ;CONTEXT= indicates
       "print lines up to and including the one that contains this string"; an
       expression indicates "print lines up to and including the one for which
       this expression is true".


MAX_820
MAX
     - ;MAX=numlines -- indicates the maximum number of lines to search and
       print.  This is also used to optimize the FSEARCHEXP(...) function when
       searching for a string in a fileset.  Ordinarily, the FSEARCHEXP(...)
       and similar functions read the ENTIRE file looking for the string
       specified.  On especially large files, this can take quite some time,
       but if all you are interested in is whether or not the file contains the
       string at all, stopping the search after you have found the first
       occurrence will save the time it takes to search the rest of the file.
       For instance, if you wanted to %COPY all of the files that contain a
       reference to a particular file (perhaps in preparation for changing the
       structure of that file), the following command could be used:

       %COPY @.FROZEN(FSEARCHEXP("'CUSTFILE';MAX=1")>0),=.WORKING

       NOTE: if you use ;MAX=numlines with ;CONTEXT=range, the %PRINT command
       will display the entire range for each occurrence of the ;SEARCH=
       string.


START_821
START
   * ";START=startrecnum" -- indicates the starting record number for the
     output.  Positive numbers indicate record numbers from the start of the
     file (1 being the first record); negative numbers indicate record numbers
     from the end of the file (-1 being the last).

     Default is 1 (the first record).


END_822
END
   * ";END=endrecnum" -- indicates the ending record number for the output.
     Positive means from start of file (1 = first record); negative means from
     end of file (-1 = last record).

     Default is -1 (the last record).


WAIT_823
WAIT
   * ;WAIT=[numseconds] -- indicates that the file may be open for output by
     another process and that MPEX should "wait" when reaching the end of file
     for more data to be produced.  If a number is specified, then MPEX will
     pause for the number of seconds specified.  After this delay, MPEX will
     check to see if any additional data has been written to the file, and if
     so, continue printing until the end of the page or until all of the new
     data has been printed.  This is primarily useful when using the %PRINTO
     command to watch the progress of a job stream.

     If the number of seconds specified is positive, MPEX will "beep" the
     terminal prior to resuming its printing.  If the number is negative, MPEX
     will remain silent when displaying any new data.

     The default is -5 (a five second delay without beeps).

     One thing to be aware of is that when using ;WAIT=, the default pagesize
     (;PAGE=) will be set to 0 and the output of the print command will
     continue until the current EOF is reached.

SEARCHING FOR STRINGS (;SEARCH=)

The MPEX %PRINT command can not only print entire filesets, but can also search
an entire fileset for a string.  For instance, you can say:

       %PRINT AP@.SOURCE;SEARCH="CUSTNUM";NUM

and MPEX will print for you (with line numbers, as per ;NUM) all the lines that
contain "CUSTNUM" in all the files in AP@.SOURCE.  This can be quite handy in
many ways -- whenever you want to find all occurrences of a variable in a
fileset of sources, of a filename in a set of job streams, of a word or phrase
in a set of documents, and so on.


Searching_for_lines_containing_any_of_a_list_of_strings_824
Searching for lines containing any of a list of strings
But wait -- there's more! You can not only search for a single string but for
MULTIPLE strings.  For instance, if you say

     %PRINT @.SOURCE;SEARCH="PROCEDURE" or "FUNCTION";NUM

MPEX will print for you all the lines that contain either the string
"PROCEDURE" or the string "FUNCTION" (thus giving you an index of all the
procedures or functions in your PASCAL programs).  Similarly, you can say

     %PRINT @.SOURCE;SEARCH="CUSTNUM" or "COMPNAME" or "DEFAULT";NUM

to print all lines that contain one of three strings, and so on.


Searching_for_lines_containing_all_of_a_list_of_strings_825
Searching for lines containing all of a list of strings
Just like you can use OR to find all lines that contain one string OR another,
you can use AND to find all lines that contain both strings:

     %PRINT @.SOURCE;SEARCH="PROCEDURE" and "FNAME"

will find you all the lines that contain both the strings "PROCEDURE" and
"FNAME" in the same line.  Similarly, you can say

     %PRINT @.JOB;SEARCH="!JOB" and NOT "MANAGER.SYS"

to find all the lines that contain "!JOB" but not "MANAGER.SYS".


Searching_for_strings_ignoring_case__826
Searching for strings ignoring case


CASELESS_keyword_in__PRINT__SEARCH__827
CASELESS keyword in %PRINT ;SEARCH=


CL_keyword__828
CL keyword
Sometimes you want to search for a string regardless of whether it appears in
UPPERCASE or lowercase.  The CASELESS SEARCHING feature permits this.  If you
say

     %PRINT @.DOC;SEARCH=CASELESS "INVOICING"

MPEX will find all occurrences of "INVOICING", "invoicing", "Invoicing", or any
other UPPERCASE/lowercase combination.  CASELESS can be abbreviated CL, e.g.

     %PRINT @.DOC;SEARCH=CL "INVOICING" and "NO"

which finds all lines that contain "INVOICING" in either UPPERCASE or lowercase
and at the same time contain "NO" in UPPERCASE.  Note that the CL applies only
to the string that immediately follows it (in this case "INVOICING") -- "NO"
will be matched only in UPPERCASE.


Searching_for_delimited_strings__829
Searching for delimited strings


DELIM_keyword_in__PRINT__SEARCH__830
DELIM keyword in %PRINT ;SEARCH=


D_keyword__831
D keyword


LDELIM_keyword_in__PRINT__SEARCH__832
LDELIM keyword in %PRINT ;SEARCH=


RDELIM_keyword_in__PRINT__SEARCH__833
RDELIM keyword in %PRINT ;SEARCH=
Say that you try searching for the string "WARD".  If you just do a

     %PRINT D@.DEV;SEARCH="WARD"

then you'll also find the strings "WARDEN", "FORWARD", "AWARDED", and so on.
What if you just want to see occurrences of the string "WARD" when it occurs as
a separate word, i.e.  delimited by special characters?

You can do this by using the DELIM keyword (which can be abbreviated to just a
D):

     %PRINT D@.DEV;SEARCH=DELIM "WARD"      or
     %PRINT D@.DEV;SEARCH=D "WARD"

This will find all the lines which contain the string "WARD" when the
characters immediately before it and after it are non-alphanumeric characters.

What if you want to find all occurrences of a string delimited on one side by a
special character? For instance, you might want to find all lines containing
the string DB preceded (but not necessarily followed by) a delimiter -- this
might match all your database-related variables (i.e.  DBTHISVAR, DBTHATVAR,
and DB_THE_OTHER_VAR, but not BLOODBANK_VAR); you can do this by saying

   %PRINT @.SOURCE;SEARCH=LDELIM "DB"

-- the LDELIM means "delimited on the left"; similarly, RDELIM means "delimited
on the right".


MPEXPRINTNONDELIMS_834
MPEXPRINTNONDELIMS
This can be especially useful for looking for all occurrences of a particular
variable name in a source file (or a fileset of source files).  However, since
most languages allow at least one special character as part of a variable name
("_" in PASCAL or C, "-" in COBOL), you want to search for all occurrences of a
string delimited by characters that are neither alphanumeric nor allowable in
variable names.

To do this, we let you set a variable called MPEXPRINTNONDELIMS.  If, for
instance, you use COBOL, you can do a

     %SETVAR MPEXPRINTNONDELIMS "-"

to tell MPEX that all %PRINT ;SEARCH=DELIM (and LDELIM and RDELIM) operations
are to consider "-"s as "non-delimiter" characters.  The %SETVAR will (like all
%SETVARs) remain in effect for the remainder of your session (or until you do a
%DELETEVAR MPEXPRINTNONDELIMS).  If you want the non-delimiter characters to be
always set to a particular value, you should put the SETVAR command into your
MPEXMGR, MPEXMGR.PUB, or MPEXMGR.PUB.VESOFT file (documented elsewhere in this
manual).  You can specify more than one character in MPEXPRINTNONDELIMS -- all
the characters you specify will be viewed as non-delimiters.

Of course, you can combine DELIM (or LDELIM or RDELIM) and CASELESS to search
for delimited strings ignoring case:

     %PRINT AP@.SOURCE;SEARCH=DELIM CASELESS "FNUM"  or
     %PRINT AP@.SOURCE;SEARCH=D CL "FNUM"

The entire ;SEARCH= parameter is really just a logical expression (much like
the logical expressions you can use in :IF, :WHILE, fileset selection
conditions, etc.).  One difference is, of course, that strings can be used in
place of booleans -- you normally wouldn't be able to say "FOO" AND "BAR", but
you can do this in the ;SEARCH= parameter.


R_835
R
However, you can actually specify an arbitrary logical expression as the
;SEARCH= parameter.  This is especially useful because the current record being
processed is available to you as a variable called "R".  Thus, you can, for
instance, say

     %PRINT @.DATA;SEARCH=(STR(R,10,5)="XYZZY");NUM


Searching_for_patterns_in_fileset_records_using_wildcards_836
Searching for patterns in fileset records using wildcards
which will output all the records that contain the string "XYZZY" in characters
10 through 14 of string R.  Similarly, you can say

     %PRINT @.DATA;SEARCH=R MATCHES "@XY?#@";NUM

which will find all occurrences of the pattern "XY?#" in the DATA files.  The @
characters at the start and end of the string indicate that the pattern can be
found anywhere in the string; just saying

     %PRINT @.DATA;SEARCH=R MATCHES "FOO@";NUM

will find all the lines that start with FOO;

     %PRINT @.DATA;SEARCH=R MATCHES "@BAR";NUM

will find all the lines that end with BAR.

Do you want to get really fancy? Try saying:

     %PRINT @.DATA;SEARCH=VALIDINTEGER(STRRTRIM(STR(R,20,5)));NUM

This will find all the lines in all the files in the DATA group that have a
valid integer in columns 20 through 24.

In addition to the variable R (the contents of the current record), the
;SEARCH= (or ;PREV=) parameter can also refer to the variable RECNUM (record
number) or LINENUM (line number).


RECNUM_837
RECNUM
RECNUM refers to the record number of the current record in the file, starting
with 1.  Thus,

     %PRINT MYFILE;SEARCH=(RECNUM MOD 2)=0

will output every other record in the file.  (This can be particularly useful
for reformatting files, especially if you use the ;OUT= parameter to send the
output to another file.)


LINENUM_838
LINENUM
LINENUM refers to the line number of the current record in the file.  If the
file is unnumbered, LINENUM is set to -1; if the file is numbered, LINENUM is
set to the EDITOR line number MULTIPLIED BY 1000 -- thus EDITOR line 1.5 has
LINENUM = 1500.

You can use LINENUM to select a range of file records, not by record number (as
;START= and ;END= do) but by line number.  Thus,


Searching_for_lines_by_line_number_839
Searching for lines by line number

     %PRINT AP@.SOURCE;SEARCH=BETWEEN(LINENUM,1000,9900)

will print lines 1.0 through 9.9 of all the files in AP@.SOURCE.  Of course,
you can do some even trickier things, for instance

     %PRINT AP@.SOURCE;SEARCH=(LINENUM MOD 1000)<>0

which will find you all the non-integer line numbers in AP@.SOURCE.  (Perhaps
this might give you a good idea of changes that were made since the last
renumbering.)

Why do we set LINENUM to an integer value (e.g.  1500 or 33250) instead of a
real number (e.g.  1.5 or 33.25)? We would have liked to use real numbers, but
unfortunately the HP3000's single-precision real numbers are not precise enough
to correctly represent an 8-digit value; for large line numbers the error would
be substantial enough to cause some serious problems.


MPEXPRINTLINESFOUND_840
MPEXPRINTLINESFOUND
If you're interested, the %PRINT command sets a variable called
MPEXPRINTLINESFOUND to the number of lines that actually contain the given
search string.  (If no ;SEARCH= parameter is specified, MPEXPRINTLINESFOUND is
set to the total number of lines in the files printed.)

A few final notes on using ;SEARCH= on the %PRINT command:

   * When you use ;SEARCH=, CONTEXT=, & ;NUM, the lines that actually contain
     the string being searched for are marked with a "*" between the line
     number and the text; any lines shown as a result of a ;PREV= are marked
     with a "-".

   * If you omit the part of the ;CONTEXT= parameter that comes before a comma,
     no lines before the one found are printed; if you omit the part that comes
     after the comma, no lines after the one found are printed.

   * When you specify the "before" part of the ;CONTEXT=, %PRINT has to read
     backwards from the point where it finds a line that matches the ;SEARCH=.
     This is rather fast for fixed-record-length files, but much slower for
     variable-record-length and QEDIT files -- keep this in mind.

STRING SEARCHES IN FILESET SELECTIONS

You can use all the power of string searching in fileset selection conditions
(using FSEARCHEXP or FSEARCHSTRING, which work like %PRINT;SEARCH=) -- for
instance,

   %COBOL @.SOURCE(FSEARCHEXP("'CUSTNO' or 'CUSTNAME'")>0), =.PUB

will recompile all your SOURCE files that mention the variables CUSTNO or
CUSTNAME! See the documentation on the file attribute functions FSEARCHEXP and
FSEARCHSTRING in the MPEX Filesets chapter.


_PRINTI_841
%PRINTI


_PRINTO_842
%PRINTO

Syntax:   %PRINTI [ #Ispoolfilenumber ]   [;mpexprintparms]
                  [ #Jjobnumber        ]
                  [   jobname         ]
                  [ #Aschedjobnumber  ]

          %PRINTO [#Ospoolfilenumber|#Jjobnumber|jobname]
          [;mpexprintparms]
          [;IFLOW]                                         (NEW)
          [;SEARCH=IFTRUE|IFFALSE]                       (NEW)

Examples: %PRINTI #J1234; SEARCH=":"
          %PRINTO MYJOB,MYUSER.MYACCT; PAGE=9999; NUM
          %PRINTO #O1234; SEARCH="CIERR" or "FSERR"; CONTEXT=-2
          %PRINTO ;WAIT;IFLOW

The %PRINTI and %PRINTO commands print, respectively, input and output
spoolfiles; you may, optionally specify any of the parameters of the %PRINT
command (see above).

If you specify a spoolfile number ("#I1234" for %PRINTI, "#O1234" for %PRINTO),
the given spoolfile will be printed.

If you specify a job number or job name, MPEX will find and print the $STDIN
(for %PRINTI) or $STDLIST (for %PRINTO) spool file of the given job.

If you don't specify either a job number, job name, or spoolfile number, the
$STDIN or $STDLIST spoolfile of the last job submitted by MPEX (via %$command,
%SUBMIT, or %SCHEDULE) or by STREAMX (see the SECURITY User Manual) or by
VEAUDIT will be printed.

%PRINTI also works on all input spool files (which, however, exist only for
currently running jobs, waiting jobs, and scheduled jobs, not jobs that have
already run), but requires SM capability.

MPE/V and MPE/iX differences: %PRINTO and %PRINTI


MPE_V_and_MPE_iX_differences___PRINTO_and__PRINTI_843
MPE/V and MPE/iX differences: %PRINTO and %PRINTI

On MPE/V, %PRINTO works only on closed output spool files (since it uses SPOOK5
to access them), and you can't use the optional "[;mpexprintparms]" parameters.
%PRINTI is not available at all on MPE/V.

USING ;WAIT, ;IFLOW, & ;SEARCH= TO VIEW $STDLISTs


Using__WAIT_844
Using ;WAIT


WAIT_845
WAIT


IFLOW_846
IFLOW


SEARCH_IFTRUE_or_SEARCH_IFFALSE_847
SEARCH=IFTRUE or SEARCH=IFFALSE

On MPE/iX, %PRINTO works on all output spool files, including ones currently
being generated by a running job.  There are a few %PRINT keywords that are
especially well suited for printing $STDLIST files.  The ;WAIT= keyword has
already been documented under the %PRINT command since it will work for any
output file, not just $STDLISTs.

When you supply the ;IFLOW keyword, %PRINTO will display the FALSE portions of
:IF/:ELSE/:ENDIF blocks in low intensity.  This makes it easier to scan the
output of a $STDLIST file since you can tell at a glance that a particular
statement was or was not executed without having to look back (perhaps several
screens) for the "*** CONDITION FALSE, COMMANDS IGNORED..." message buried in
the $STDLIST.

The ;SEARCH= attribute IFTRUE takes the above concept a step further and allows
you to filter out the false portion of a job stream entirely.  Or, if you
prefer, you can use ;SEARCH=IFFALSE to just view the parts of a job that were
not executed.  In either case, if something appears in the listing that should
not have, then it is a simple matter to look back at the preceding condition to
determine why it was not evaluated correctly.


_PROGINFO_848
%PROGINFO

Syntax:   %PROGINFO progname

Examples: %PROGINFO DBUTIL.PUB.SYS


MPE_V_and_MPE_iX_differences___PROGINFO_command_849
MPE/V and MPE/iX differences: %PROGINFO command
Note: %PROGINFO only works on MPE/V (and Compatibility Mode) programs.

Ever want to find out some detail about a program file? Well, here's a command
that will display a great deal of information about a compatibility mode
program.

For example, %PROGINFO QUERY.PUB.VESOFT may show the following:

FILE: QUERY.PUB.VESOFT     CAPS   : BA IA MR       MAXDATA: 32767
DL  : 0                    STACK  : 1200           DBSIZE : 12830
DB AREA RECNUM: 1          EXTERNALS RECNUM: 862   ENTRY RECNUM: 872
FPMAP RECNUM: 873
CREATED 91/03/25,  2:21 PM    LAST ACCESSED 91/06/28, 10:05 AM
SEG   LEN REC#     SEG   LEN REC#     SEG   LEN REC#     SEG   LEN REC#
  0  2260  102       1  2176  120       2  7516  137       3  6396  196
  4  7544  246       5  2072  305       6  8456  322       7  8124  389
  ...
ENTRIES: QUERY'C'00'00(main) BUGS SEARCH
EXTERNALS: ASCII BIMAGEVERSION BINARY CALENDAR CATCLOSE CATOPEN CATREAD
    CAUSEBREAK CLOCK COMMAND COMPLIBINFO DASCII DBBEGIN DBCLOSE
    DBCONTROL DBDELETE DBEND DBERROR DBFIND DBGET DBINARY DBINFO DBLOCK
    DBMEMO DBPUT DBUNLOCK DBUPDATE DEBUG DFLOAT' DIVD DLSIZE EXTIN'
    ...
    SORTOUTPUT SORTTITLE TERMINATE TERMINATE' UNLOADPROC VEOPEN WHO
    XARITRAP XCONTRAP ZSIZE

As you can see, this copy of QUERY doesn't call DBOPEN! Instead, it calls
VEOPEN, VESOFT's improved version of DBOPEN (see the section Database Security
in the SECURITY User Manual for details).


_PURGE__Deletes_a_file_or_fileset_850
%PURGE: Deletes a file or fileset


Disc_space_851
Disc space

Syntax:   %PURGE fileset [,TEMP]
          [;YES]

Examples: %PURGE K#######.@.@+LOG####.PUB.SYS
          %PURGE @,TEMP;YES

          %PURGE @.@.@ - @.@.VESOFT(ACCDATE<TODAY-120 and NOT ISPRIV)
          %PURGE /     - /VESOFT/ (ACCDATE<TODAY-120 and NOT ISPRIV) (POSIX)

The %PURGE command lets you -- you guessed it -- purge entire filesets, saving
a lot of disc space in the process.  For instance,

   %PURGE K#######.@.@+LOG####.PUB.SYS

will purge all your EDITOR K-files and your system log files;

   %PURGE @.@.@ - @.@.VESOFT(ACCDATE<TODAY-120 and NOT ISPRIV)
   %PURGE /     - /VESOFT/ (ACCDATE<TODAY-120 and NOT ISPRIV) (POSIX)

will purge all the files in the system that haven't been accessed in 120 days
except for databases or other PRIV files (You might do an %MPEXSTORE first to
:STORE them to tape and then do the %PURGE.)

The ,TEMP option allows you to %PURGE temporary filesets (just like MPE's
:PURGE,TEMP allows you to :PURGE single temporary files)!

Another application for %PURGE is purging all of the files in an account:

   * without locking up the directory (which the :PURGEACCT does, sometimes for
     minutes, while it purges all the files);

   * without destroying the users and groups within the account.

If you want to save space by deleting an account (e.g.  the contributed
library, TELESUP, etc.), you can :STORE all the files and then do a

   %PURGE @.@.TELESUP

This will delete the files but leave the accounting structure intact --
whenever you want to :RESTORE any files into the account, you won't have to
worry about specifying the ;CREATE keyword or making sure all the groups have
the right capabilities and access masks, etc.

Also note that the %PURGE command allows a system manager, an account manager
(in his own account), or a database's creator to %PURGE a database just like he
would a normal fileset.

AUTOMATIC VERIFICATION TO AVOID MISTAKES

A natural concern that most people have is: what if I accidentally mess up? You
meant to say %PURGE @.@.@-@.@.VESOFT(ACCDATE<TODAY-120), but instead you typed:
   %PURGE @.@.@ - @.@.VESOFT (ACCDATE>TODAY-120)
Wow! Now that wouldn't be very nice.

As the old saying goes, "to err is human, but to really foul things up, you
need a computer".  Just as the power of MPEX can make it very easy to do things
that you want to do, it can make it very easy to accidentally do things that
you don't really want to do.

Fortunately, MPEX has some very important fail-safes that can vastly decrease
your chances of error.  The most important one is that

   Before doing ANY real %PURGEs, MPEX will first show you the names of all the
   files that are to be purged.

For instance, let's say you type:

   %PURGE SA@.SOURCE

The output you get might look like this:

-----Will purge SAMSFILE.SOURCE.AP (code "EDTCT", type FA, 1333 sectors)
-----Will purge SAR010X.SOURCE.AP (code "EDTCT", type FA, 4001 sectors)
-----Will purge SATURDAY.SOURCE.AP (code "", type FB, 128 sectors)
-----Will purge SAZ999.SOURCE.AP (code "", type VAM, 22 sectors)
5484 sectors will be saved
OK to purge 4 files (y/n)?

So far, none of the files have actually been touched.  If you say "N" (or press
[RETURN]), MPEX will say

   Error: Operation aborted by user request.

and the files will remain intact.

If, however, you answer "Y" to the "OK to purge?", MPEX will actually purge the
files:

   -----Purging SAMSFILE.SOURCE.AP (1333 sectors)
   -----Purging SAR010X.SOURCE.AP (4001 sectors)
   -----Purging SATURDAY.SOURCE.AP (128 sectors)
   -----Purging SAZ999.SOURCE.AP (22 sectors)
   5484 sectors saved
   %

This way, if you inadvertently specify the wrong fileset, you'll get to see all
the files that are to be purged before they're actually touched.  Then, if you
see your production database come up on the list, you'll know that something's
wrong...

Note that when MPEX shows you the "-----Will purge ..." information, it not
only shows you the filename, but also the filecode, the record type (which is
the same as the "TYP" column in a :LISTF ,2 listing -- FA, for instance, means
Fixed Ascii), the file size in sectors, and the number of records in the file
(not shown in the above example).  This gives you an additional chance to make
sure that the files being purged are actually the ones you want to purge.

A few other alternatives exist if you want to be really secure about all this.
For instance, you can add to your MPEXMGR.PUB.VESOFT file (which is
automatically executed whenever anyone enters MPEX) the commands:

   %SET CAPABILITY,PURGE,AM
   %SET DEFAULT,PURGE,?

   * The first command (%SET CAPABILITY) indicates that the %PURGE command can
     only be used by people with AM capability working inside their own
     accounts (except that SM users can always use any command).

   * The second command says that if a user types "%PURGE" (rather than
     "%!PURGE" or "%$PURGE"), he'll be prompted Yes/No for each file in the
     fileset, as well as once for the entire fileset.

If you're really concerned about accidental damage done with the %PURGE
command, you may use one or both of these commands; however, we believe that
the fileset-level yes/no verification that the %PURGE command now provides
should be more than enough.

If, on the other hand, you do not want to have all this verification -- if you
want the %PURGE to be done without prompting -- you can add ";YES" to the
command.

As an alternative, you can set the JCW MPEXYESPURGE to 1 to cause all %PURGE
commands to act like %PURGE...;YES.  We implemented this because a number of
users requested it; we do not recommend that you do this, but if you want to
live dangerously, go ahead.

A better alternative is to set the MPEXYESPURGEONE JCW to 1.  This means "don't
ask yes-or-no when the %PURGE command specifies a single file rather than a
fileset." This is especially useful when you want to execute an MPE/iX command
file and don't want to be prompted every time it attempts to purge a single
file.

Note that if you execute a %PURGE command in batch (by saying %$PURGE ...,
%SCHEDULE PURGE ..., or %SUBMIT PURGE ...), the %PURGE command will (naturally)
not ask for verification, since it'll be running in batch where there's nobody
to ask.

However, remember that whenever you submit a job via $, %SCHEDULE, or %SUBMIT,
MPEX asks you "OK to stream (y/N)? " -- this is your last chance to say
"whoops! I didn't really mean it!".


_PURGELINK_852
%PURGELINK

Syntax:   %PURGELINK fileset [;YES]

Examples: %PURGELINK MYLINK
          %PURGELINK ./LISTS/linkfiles
          %PURGELINK ./Testdir/ ;YES

This command lets you PURGE symbolic link files created by the %NEWLINK
command.  Since symbolic link files are a POSIX related feature of the
operating system, this command is only available on machines that support
POSIX.  (See the %NEWLINK command for a discussion of LINK files)

Note that like our %PURGE command for filesets, this command prompts for
verification before actually purging the link files.  If you are certain that
the links can be purged without verification, then you can either use ;YES on
the command, or set the variable VESOFTDEFAULTPURGELINK to ";YES".

It is important to realize that purging the LINK file does not purge the ACTUAL
file, merely a pointer to the file.  If you inadvertently purge a link file,
the data is still in the original file.


_QEDIT_853
%QEDIT

Syntax:   %QEDIT fileset, qeditcommand

Examples: %QEDIT @.SRC, LIST @ LP
          %QEDIT @.SRC, LIST "FCONTROL"
          %QEDIT @.SRC, CHANGE "ACCT-NUM", "ACCOUNT-NUM", @

The %QEDIT command lets you execute QEDIT commands on an entire fileset.
(QEDIT, a product of Robelle Consulting Ltd., is a powerful text editor that
many of our customers -- and we ourselves -- use.)

For instance, to list all the files in the SRC group to the line printer, just
say:

   %QEDIT @.SRC, LIST @ LP

This will execute the QEDIT /LIST @ LP command on the fileset.  Similarly,

   %QEDIT @.SRC, LIST "FCONTROL"

will display (to the terminal) all occurrences of the string "FCONTROL" in your
SRC group files.  The command

   %QEDIT @.SRC, CHANGE "ACCT-NUM", "ACCOUNT-NUM", @

will change all occurrences of "ACCT-NUM" to "ACCOUNT-NUM" in your SRC group
files.

HOW IT WORKS

MPEX does slightly different things depending on the type of the file and on
the QEDIT command being executed:

   * If the command is a /LIST, MPEX uses QEDIT's "list external file" feature
     to /LIST the file without /OPENing it or /TEXTing it.  This is quite a bit
     faster and also doesn't change the file's last modify date.

   * If the command is not a /LIST but the file being processed is a QEDIT
     file, MPEX will /OPEN the file and execute the command.

   * If the command is not a /LIST and the file being processed is not a QEDIT
     file, MPEX will /TEXT the file, execute the command, and /KEEP the file.

One thing you should be warned about is this: if you do a non-/LIST on a
non-QEDIT file, MPEX will always tell QEDIT to do the /TEXT and /KEEP (but we
do use QEDIT's "IFDIRTY" option).  This is usually not a problem at all, since
a useless /KEEP will just recreate the file.

However, in a few cases, it is possible that the rebuilding of the file by
/KEEP might damage the file structure in some way -- for instance, if the file
is a KSAM file, a VFORM file, or something like that, you might want to exclude
it from the command.  You can easily do it with MPEX filesets:

   %QEDIT @.SRC(ISQEDIT or ISASCII),C "ACCT-NUM","ACCOUNT-NUM",@

This will do the /CHANGE on only those files in the SRC group that have code
QEDIT or are ASCII.


_QUIT_854
%QUIT

Syntax:   %QUIT [[CIERR=] errnum]

Examples: %QUIT
          End Run

          %QUIT 10
          Program terminated in an error state.  (CIERR 976)

The %QUIT command is a modified version of MPEX's %EXIT command.  Unlike %EXIT,
%QUIT always terminates the active MPEX process, without attempting to suspend
MPEX inside of the current father process.

Practically, the only time you need %QUIT is when you're running MPEX from
within a process-handling environment that isn't smart enough to allow you to
reactivate suspended son processes (for example, when running copies of
CI.PUB.SYS on an MPE/iX system).

%QUIT checks to see if MPEX has any active son processes (perhaps as a result
of using the %GOON command), and will fail if any active son processes exist.
You must either wait for the active sons to terminate, or use the %KILL command
to terminate them before %QUIT will succeed.


CIERR_855
CIERR
%QUIT also accepts an optional CIERR parameter.  If a non-zero CIERR parameter
is supplied, MPEX will terminate with the system JCW set to the value
FATAL+CIERR.  This allows you to signal to the father process that MPEX has
terminated in an error state, and to pass an error code at the same time.


_REDO_856
%REDO

Syntax:   %REDO     [abscmdnum      ]  [,editstring]
                    [-relcmdnum     ]
                    [cmdnum1/cmdnum2]
                    [["][@]string["]]

          %DO       [abscmdnum      ]  [,editstring]
                    [-relcmdnum     ]
                    [cmdnum1/cmdnum2]
                    [["][@]string["]]

          %LISTREDO [abscmdnum1[/abscmdnum2]]  [;OUT=outfile]
                    [-relcmdnum[/-relcmdnum2]]  [;REL|ABS|UNN]
                    [["][@]string["]         ]

Examples: %DO -2
          %DO 155/158
          %DO "MYUDC A,B"
          %REDO 155
          %REDO RUN
          %REDO @MYFILE
          %LISTREDO
          %LISTREDO -30/-1

          %,155         same as %REDO 155   (, abbreviates %REDO)
          %,,           same as %LISTREDO   (,, abbreviates %LISTREDO)
          %,.-6/-1      same as %DO -6/-1   (,.  abbreviates %DO)

(Note: MPE/iX users might already be familiar with most of the features of
          these commands, since they're patterned on the MPE/iX commands with
          the same names.  For information on our enhancements to these
          commands, see the MPEX AND MPE/iX section of the USING MPEX chapter.)

Everybody makes mistakes (even you!).  When you mistype an MPEX command, you'd
like to be able to easily correct your typo without having to re-enter the
whole thing.

Say that you enter

   %RUN MYPROG;MAXDATA=30000;INFO="MYFILE.DATA.SYS";PARMN=555

You entered PARMN instead of PARM, and MPEX will give you a syntax error
message.  Now, you can (just as in MPE) type

   %REDO

and the command will appear for you to edit; after you make your modification
(presumably deleting that "N"), you press [RETURN], and MPEX re-executes the
modified command.

This is all well and good, but what if the bad command wasn't the last one you
typed, but the second-to-last? You tried running the program, but it didn't
exist; then you did a :LISTF to find out the true program name.  Now the RUN
command -- all 57 characters of it -- isn't the last command any more, but you
still want to %REDO it.

MPEX lets you do this.  By default, it saves in the command history the last
1000 commands you typed, and every one of them is available for you to

   * Examine with the %LISTREDO command.

   * Edit and re-execute via the %REDO command.

   * Immediately re-execute (without editing) using the %DO command.

Because of its size, the command history can be used for much more than just
correcting typos:

   * You can have a sort of "instant function key" -- say that you're working
     on a particular program and type a long %PREP command; next time you need
     to do the %PREP, you can just say

        %DO PREP

     and that command will be automatically re-executed.  You only need to type
     the command once.

   * You have a complete log of all the MPEX commands you've typed in this MPEX
     session (we'll discuss later how you can save them permanently so they'll
     be accessible even after you exit MPEX and re-enter later).

     You can see whether you indeed did what you thought you did, whether the
     sequence of commands you typed which triggered a particular condition was
     what you thought it was, and so on.

   * And, of course, you can still use %REDO to correct typos.

REFERRING TO SAVED COMMANDS

In order to %REDO (or %DO) a command, you need to tell MPEX which command is to
be redone.  There are several ways of doing this:


_REDO__redoing_the_last_line_857
%REDO: redoing the last line
   * If you simply say

        %REDO

MPEX will %REDO the last command you typed (just like MPE/V's :REDO).


_REDO__finding_line_to__REDO_by_leading_string_858
%REDO: finding line to %REDO by leading string
   * If you say

        %REDO RUN           (%REDO followed by a string)

     MPEX will %REDO the last command (if any) that starts with the string RUN.


_REDO__finding_line_to__REDO_by_contained_string_859
%REDO: finding line to %REDO by contained string
   * If you say

        %REDO @MYFILE       (%REDO @string)

MPEX will %REDO the last command that CONTAINS the string MYFILE.


_REDO__absolute_line_numbers_860
%REDO: absolute line numbers
   * If you say

        %REDO 177

     MPEX will %REDO the command with the ABSOLUTE COMMAND NUMBER 177.  How do
     you know a command's absolute command number? You might know it from a
     %LISTREDO:

        %LISTREDO
        ...
        176) PURGE MYFILE
        177) PREP MYUSL,MYFILE;CAP=PH,PM,DS;MAXDATA=30000;RL=...
        178) RUN MYFILE
        ...

     or, if you've set MPEXPROMPT to include the command number (see below),
     you'll be able to see each command number on the screen as the command is
     entered:

        (cmd176) % PURGE MYFILE
        -----Purging MYFILE.DEV.VESOFT
        (cmd177) % PREP MYUSL,MYFILE;CAP=PH,PM,DS;MAXDATA=30000;...
        ...
        (cmd184) %


_REDO__relative_line_numbers_861
%REDO: relative line numbers
   * If you say

        %REDO -3

MPEX will redo the 3rd-to-last command you've typed.  Your most recently typed
     command is referred to as -1, so

        %REDO

is really the same as

        %REDO -1


_REDO__line_ranges_862
%REDO: line ranges
   * If you say

        %REDO 177/180

     then MPEX will redo lines 177, 178, 179, and 180, prompting you for
     modifications for each and then re-executing each.

     This is most useful on the %DO command (which re-executes a command
     without prompting for modifications): say that you've typed a sequence of
     6 commands that you want to re-execute -- you can type

        %DO -6/-1         << relative, or >>
        %DO 179/184       << absolute >>

     A good example of this is if you enter a multi-line >REPORT statement in
     QUERY (as we'll discuss later in the Running MPEX section, under "MPEX
     HOOK", VESOFT makes the REDO facility available in QUERY, in EDITOR, etc.)
     -- a single DO command can re-execute the entire report in one fell swoop.

EDITING THE COMMAND BEING %REDOne


_REDO__editing_characters__863
%REDO: editing characters

In addition to letting you redo the last 1000 commands, MPEX makes it easier
for you to edit them.

Instead of just the usual R, I, and D editing characters, MPEX also lets you
say:

   * >xxx               to append "xxx" to the end of the
                     line.

   * >DDDDD             to delete five characters (one for each D) from the
                     end of the line.

   * >Rxxxx             to replace the last 4 characters (in this case) of the
                     line by "xxxx".

   * D>                 to delete until the end of the
                     line.

   * C/xx/yy/           to change all occurrences of "xx" into "yy"; you
                     may use any non-alphanumeric character like
                     ' or " or / or , as a delimiter.

For example:

   %REDO RUN
   RUN myprod;LIB=G;MAXDATA=34000;INFO="TESTING 123"
                                D>
   RUN myprod;LIB=G;MAXDATA=34000
   >;PARM=555X
   RUN myprod;LIB=G;MAXDATA=34000;PARM=555X
   >D
   RUN myprod;LIB=G;MAXDATA=34000;PARM=555
   C/34/30/
   RUN myprod;LIB=G;MAXDATA=30000;PARM=555

Try it out -- it's a good deal more powerful than ordinary :REDO.

Actually, there's an even more powerful editing facility that you can use in
:REDO (and also in EDITOR -- see "MPEX HOOK" for more details).  It is called
VEMODIFY, and it uses the full power of your HP terminal to provide you a
"full-line" modification facility.  To use it, say

   :SETJCW HPREDOVEMODIFY=1

See the VEMODIFY section for information on this.  (Or try it -- do the
:SETJCW, :REDO a line, and press <control-Q> to get help.)

Finally, note that if you know exactly what modifications you need to make, you
can specify them on the %REDO or %DO commands:

   %RUN MYFILE;LIB=G;STDIN=XFILE;INFO="BANANA";PRAM=123
   Error: Expected one of the MPE :RUN parameters ...
   %DO ,C/PRAM/PARM/

Since we knew that the error was our "PRAM" typo, we immediately specified
"C/PRAM/PARM/" to change the PRAM into PARM -- this modification will be made
and the command will be re-executed without any further prompting.

If you specify this edit string, %DO and %REDO behave identically: both execute
the edit, and neither prompts for any more modifications.

ABBREVIATIONS FOR %REDO, %DO, AND %LISTREDO


_REDO_864
%REDO

Since %REDO is largely present to save you typing, it would be a shame if you
had to say LISTREDO and REDO all the time -- you might end up typing more than
if you had just re-entered the entire command.

This is why we permit you to abbreviate all three commands:

   ,                in place of REDO
   ,,               in place of LISTREDO
   ,.               in place of DO

Thus, you might say:

   %,,
   1079) FILE COPYLIB=MYCOPY
   1080) $COBOL AP010S,AP010P,,,,,MAXDATA=30000
   1081) $COBOL XFILE.SOURCE,XPROG.PUB,,,,,CAP=PH,DS;RL=MYRLFILE
   ...
   %,.1079/1081
   << MPEX now re-executes commands 1079 through 1081 >>
   FILE COPYLIB=MYCOPY
   $COBOL AP010S,AP010P,,,,,MAXDATA=30000
   OK to stream (Y/N)? Y
   #J123
   $COBOL XFILE.SOURCE,XPROG.PUB,,,,,CAP=PH,DS;RL=MYRLFILE
   OK to stream (Y/N)? Y
   #J124
   << MPEX is done re-executing 1079/1081; it prompts you again >>

%RUN MYFILE.DATA.PROD;LIB=G;INFO="BANANA";PARM=177
   PROGRAM FILE NOT FOUND.  (CIERR 622)
   %LISTF MYFILE.@.PROD,1
   ...
   %,RUN
   RUN MYFILE.DATA.PROD;LIB=G;INFO="BANANA";PARM=177
   C/DATA/PUB/
   RUN MYFILE.PUB.PROD;LIB=G;INFO="BANANA";PARM=177

...

As you see, in place of the LISTREDO, REDO, and DO commands, we used their
abbreviations -- in all other respects, the commands worked just as if they'd
been fully spelled out.

%LISTREDO parameters

The %LISTREDO command has several parameters that are worth mentioning:

   %LISTREDO                 shows the last 20 commands you've typed.

   %LISTREDO 10/50           shows commands #10 through #50 (pausing every
                        23 lines for you to press [RETURN]).

   %LISTREDO 10              shows commands #10 through the most recent one.

   %LISTREDO -25/-10         -- you can use relative command numbers, too.

   %LISTREDO RUN             shows all the commands that start with RUN.

   %LISTREDO @MYFILE         shows all the commands that contain MYFILE.

   %LISTREDO 10/15;ABS       shows commands with absolute command numbers
                        (the default).

   %LISTREDO 10/15;REL       shows commands with relative command numbers.

   %LISTREDO 10/15;UNN       shows commands without command numbers.

   %LISTREDO;OUT=*LP         sends all the output to the given file (*LP).

   %LISTREDO 1               shows all the commands saved in the history
                        (not just the last 20).

All of the above options -- the command specification (1, 10/15, RUN, etc.),
the numbering scheme (;ABS, ;REL, or ;UNN) and the ;OUT= file may be combined
any way you like.

SAVING YOUR COMMAND HISTORY AS A PERMANENT FILE


_REDO__saving_command_history_in_a_PERMANENT_file_865
%REDO: saving command history in a PERMANENT file

By default, your command history is kept in a program-temporary file.  When you
leave MPEX, all the saved commands are forgotten.

However, if you want to, you can save the command history so that even if you
:BYE off and then log on again tomorrow, when you re-enter MPEX all the saved
commands will be available to you.

To do this, just say:

   :FILE MPEX.REDO.VESOFT=MYREDOFL

MYREDOFL can be any file you want to; the first time you run MPEX with this
file equation, MPEX will build MYREDOFL with all the right parameters.  Then,
every time you run MPEX after that (assuming the :FILE-equation is still in
effect), MPEX will use that file as the "command history file"; any new
commands you enter will be appended to the file.

As you can see, this is geared towards letting everybody have their own REDO
files -- you might even have a system logon UDC that includes the command

   :FILE MPEX.REDO.VESOFT=MPEXREDO

This way (assuming everybody has his own group), each person will have his own
command history file.

Note that you can't have several people sharing the same command history file
-- MPEX opens it exclusively.

SETTING MPEX PROMPT TO MAKE %REDOing EASIER


_REDO__setting_MPEXPROMPT_for_ease_of_redo_866
%REDO: setting MPEXPROMPT for ease of redo

The one difficulty that you may sometimes face is identifying the command that
you want to %DO or %REDO.  There may be several commands that start with the
same characters (so just saying %REDO RUN [or whatever] won't work); you could
always do a %LISTREDO and try to find it there, but that might be more trouble
than it's worth.

Many people like to address this by changing the MPEX prompt to include the
MPEX variable HPCMDNUM.  HPCMDNUM contains the command number of the current
command -- exactly the thing you need to later %REDO it.  Thus, you might say:

   %SETVAR MPEXPROMPT "(!!HPCMDNUM) Yes, boss? "

Now, MPEX will prompt you with something like

   (391) Yes, boss?

Now, if you ever want to %REDO or %DO the command that you enter here, you'll
know that it is command number 391.  As long as it's still on the screen (or in
your terminal memory), the command number will be right there in front of you.

This is only one of the many nice things you can do with the MPEXPROMPT
variable.  You might, for instance, say:

   %SETVAR MPEXPROMPT "(!!HPCMDNUM !!HPUSER !!HPTIMEF) "

This will make every MPEX prompt show the command number, your logon user name,
and the current time.

:REDO, :DO, AND :LISTREDO IN OTHER PROGRAMS


_REDO_867
%REDO

As useful as :REDO, :DO, and :LISTREDO are in MPEX, they can be even more
useful in other programs, like EDITOR, QUERY, FCOPY, etc.  We don't mean just
:REDOing MPEX commands that you've executed from the program, but rather
:REDOing the program's own commands.

For instance, you run :FCOPY, type a long FROM=;TO=;...  command, and find that
you've made an error -- you'd like to use :REDO to redo that FCOPY command.
You may type an eight-line >REPORT command in QUERY, and then find that you
need to do another >FIND and :DO all the commands again.

The "MPEX HOOK" facility allows you to do exactly this, and more:

   * It lets you :REDO, :DO, and :LISTREDO all commands you type in a
     particular utility (with all of the features we talked about above).

   * It lets you execute MPEX commands -- including the compile commands,
     %PREP, %RUN, and UDCs -- from within EDITOR, QUERY, etc.

   * It lets you (if you have SM) save files in other accounts -- /KEEP into
     other accounts in EDITOR, copy into other accounts in FCOPY, etc.

%REDO FACILITY OPTIONS

There are several options you can set for the REDO facility (which apply
equally to the REDO facility available from MPEX HOOKed programs).  They are
set by defining various specially-named JCWs and/or variables.  Note: these
JCWs must be set before issuing a %INITREDO command or running a HOOKed program
within which you wish them to take effect.


HPREDOSIZE_868
HPREDOSIZE


MPEXREDOSIZE_869
MPEXREDOSIZE
   :SETJCW MPEXREDOSIZE=200          sets the number of commands saved in the
                                history (default 1000).
   :SETVAR MPEXREDOSIZE=200          On MPE/iX systems, you should use :SETVAR
                                instead of :SETJCW.  Note: due to the way
                                MPE/iX handles the HPREDOSIZE variable, setting
                                HPREDOSIZE outside of MPEX has no effect.
                                Setting HPREDOSIZE inside MPEX is translated to
                                MPEXREDOSIZE for compatibility.


HPREDOVEMODIFY_870
HPREDOVEMODIFY
   :SETJCW HPREDOVEMODIFY=1          turns on VEMODIFY mode in :REDO (default 0
                                = OFF).


VESOFTVEMODIFYBIT8CHECK_871
VESOFTVEMODIFYBIT8CHECK
   :SETJCW VESOFTVEMODIFYBIT8CHECK=  (used for terminals that support 8-bit
                                ASCII, such as a 2392, when using the EXTEND
                                key)
                                     0 if bit 8 is set, discard the character
                                and beep
                                     1 strip bit 8
                                     2 accept full 8-bit characters


VESOFTVEMODIFYEXPANDOK_872
VESOFTVEMODIFYEXPANDOK
   :SETJCW VESOFTVEMODIFYEXPANDOK=1  (used on 700/9x terminals and emulators)
                                     This JCW causes MPEX to use escape
                                 sequences to position the cursor which are not
                                 dependent upon the terminal width.
                                     By default, VEMODIFY assumes that your
                                 terminal is 80 columns wide, and uses escape
                                 sequences that won't work correctly if you
                                 have a 132 column wide terminal.
                                     VEMODIFY uses much longer escape sequences
                                 when you configure it this way, so we suggest
                                 you only use this mode when connected over a
                                 high speed line.


HPREDODEFLIST_873
HPREDODEFLIST
   :SETJCW HPREDODEFLIST=200         sets the default number of lines listed by
                                a simple parameter-less %LISTREDO (default 20).


HPREDONODUPS_874
HPREDONODUPS
   :SETJCW HPREDONODUPS=1            tells MPEX that if exactly the same
                                command is entered several times in a row, only
                                one copy of it will be saved (default 0 = every
                                command you type will be saved, even if it's
                                the same as the last one).

Actually, we think that our defaults are pretty reasonable, but we give you
these options just for additional flexibility.


_RELEASE_875
%RELEASE


IMAGE_databases__releasing_876
IMAGE databases: releasing

Syntax:   %RELEASE fileset
          [;KEEPAMDATES]

Examples: %RELEASE MYDB+MYDB?#

   WARNING: The Programmer General has determined that :RELEASEing files (in
            MPE or MPEX) can be dangerous to the health of your system security
            -- see the %SECURE command documentation for more information.

The %RELEASE command is just like MPE's :RELEASE, except that:

   * It works on FILESETS.

   * It does not require creator access.  It can be used by anybody with Read,
     Write, and eXecute access to a file (since anyone who has
     Read/Write/Execute access can already do anything he pleases to the file).


KEEPAMDATES_877
KEEPAMDATES
   * The ;KEEPAMDATES keyword allows you to release a file (or fileset) without
     changing that file's last Access and Modify dates.

Practically speaking, we don't encourage you to :RELEASE any files, much less
filesets.

IMAGE databases are an exception -- since they're protected by IMAGE security
(and can't be accessed normally because of their "PRIV" filecodes), it's quite
safe and often quite necessary to release them.

You can release a database very easily by saying:

   %RELEASE MYDB+MYDB?#

(to :RELEASE the root file and all the datasets); you can release all the
databases in a group by saying:

   %RELEASE @.DATA(ISPRIV)

Of course, you can %RELEASE any filesets you'd like -- you might say:

   %RELEASE @.SOURCE(ISASCII)

to release your source files, or what have you.  However, we advise you to
:RELEASE files as little as possible, since :RELEASEing a file removes all
security restrictions from it, allowing anybody to do anything to the file.


_REMOTE_HELLO_878
%REMOTE HELLO

Syntax:   %REMOTE HELLO remotelogon

Examples: %REMOTE HELLO USER.ACCT;DSLINE=SYSB
          %REMOTE:SYSB HELLO USER.ACCT
          %DSLINE SYSB
          %REMOTE HELLO USER.ACCT

SECURITY's STREAMX and logon menus allow you to avoid having remote passwords
embedded in job streams or menus; SECURITY will automatically prompt the user
for the remote passwords, or even insert them without prompting (if you
configure the system for this).  Of course, if you choose to have the passwords
automatically inserted, you can control for which users and which job
streams/menu files this will be done.

If you use SECURITY, you will also be allowed to do the same inside MPEX
command files or UDCs.  If, for instance, you want to have an MPEX command file
that logs on to a remote system, does some work on it, and immediately logs
off, you can configure SECURITY to tell MPEX to insert the appropriate
passwords into the REMOTE HELLO command (but only for this particular command
file and only for a particular set of users that you can configure).

For more information on this, see "REMOTE HELLO Processing In LOGON MENUs And
In MPEX" in the "STREAMX And !REMOTE HELLO" chapter of the BATCH ACCESS
SECURITY section of the SECURITY User Manual.

Since this is fundamentally a SECURITY feature (implemented in MPEX only for
additional convenience), it is available only for those MPEX customers who are
also licensed to use SECURITY.


_RENAME_879
%RENAME

Syntax:   %RENAME fromfileset, tofileset
          [;KEEPAMDATES]
          [;CREATE[Q]]                                     (POSIX)
          [;LOCAL[GROUPID]]                                (POSIX)
          [;DELACD]                                        (POSIX)

Examples: %RENAME MYDB@(ISPRIV), NEWDB@
          %RENAME @.UTIL(ISPROG and PROG.PMCAP),@.PRIVUTIL
          %RENAME @.OLDGROUP,@/=.NEWGROUP; KEEPAMDATES

          %RENAME ./src/project11/@, ./arc/proj11/@ ;CREATE    (POSIX)

The %RENAME command is quite similar to MPE's :RENAME, but with the following
extensions:

   * Of course, it works on filesets, including all the MPEX extensions (+
     filesets, - filesets, and selection criteria).


IMAGE_databases__renaming_880
IMAGE databases: renaming
   * It works on IMAGE databases as well as normal files --

       %RENAME MYDB@(ISPRIV), NEWDB@

     will rename the database MYDB (the root file and all the datasets) into
     NEWDB.  Note the ISPRIV selection criterion, which makes sure that only
     the database (and not any of the other files that may start with MYDB) is
     renamed.

   * It does not require the user to be the file's creator.  It can be used by
     anybody with Read, Write, and eXecute access to a file (since anyone who
     has Read/Write/Execute access can already do anything he pleases to the
     file -- for instance, copy it and purge the original).

     If you have SM capability, this command allows renaming across account
     boundaries!

   * Note that MPEX's %RENAME, just like MPE's :RENAME, does not work on
     compatibility mode KSAM files.  In fact, if you %RENAME either a KSAM data
     file or a KSAM key file, your file will probably become inaccessible until
     you %RENAME it back to its original name (again, this is just like MPE's
     :RENAME).

     The only time when %RENAME will work on a KSAM file is if you rename both
     the data file and the key file into files with the same names as before
     but in another group.  In this case (e.g.  when you do a %RENAME
     @.OLDGROUP,@.NEWGROUP), the files will be handled properly.

     MPE/iX's Native Mode KSAM stores both the data and keys in a single file,
     which can be %RENAMEd!


KEEPAMDATES_881
KEEPAMDATES
   * The ;KEEPAMDATES keyword allows you to rename a file (or fileset) without
     changing that file's last Access and Modify dates.


CREATE_882
CREATE
   * On systems that support POSIX, the ;CREATE keyword will create any
     directories needed to build the file.  The ;CREATEQ keyword builds the
     directories without displaying any messages ("quiet" mode).  For example,
     to move all of the files in a source directory into an archive directory,
     building any necessary subdirectories along the way, you could use this
     command:


LOCALGROUPID_883
LOCALGROUPID


DELACD_884
DELACD
   * Also for POSIX systems, there are additional MPE security restrictions
     placed on files that are not in their own "filegroup" (see the %ALTFILE
     POSIX NOTE regarding file security for additional details).  MPE uses ACDs
     and group/owner information to implement this additional security, and
     MPEX adds the same ACDs when renaming files from one account to another.
     MPEX has two options for %RENAME that allow you to %RENAME files from one
     account to another and have it actually belong to the new account.

     The ;LOCALGROUPID keyword (which may be abbreviated to just ;LOCAL) tells
     MPEX to rewrite the GROUP & OWNER information so that the file appears to
     be owned by the account manager of the target account.

     The ;DELACD keyword removes the additional ACDs that MPE applies when
     RENAMEing a file from one account to another.  These ACDs enable the
     original owner or creator to maintain access to the file as if it were in
     the original account.

%RENAME ./source/proj11//@, ./archive/proj11//= ;CREATE

-----Renaming ./source/proj11/main.c   => ./archive/proj11/main.c
Directory  "/XYZCORP/DEV/archive/proj11" created
-----Renaming ./source/proj11/subs.c   => ./archive/proj11/subs.c
...

Some useful applications:

   * Renaming databases, shown above.

   * Moving files that match a particular selection criterion into a particular
     group.  For instance,

        %RENAME @.UTIL(ISPROG and PROG.PMCAP),@.PRIVUTIL

     will rename all the privileged program files (PROG.PMCAP) from the UTIL
     group into the PRIVUTIL group (which might have more stringent security);

        %RENAME @.DEV-S@.@(ACCDATE<TODAY-120),@.ARCHIVE

     will move all the DEV files (except for those starting with S) that
     haven't been accessed in 120 days into the ARCHIVE group.

LOCKWORDS AND %RENAME


Lockword__on_the__RENAME_command_885
Lockword: on the %RENAME command

As we discuss in the MPEX And Your System Security section, MPEX is quite
intelligent in its lockword handling.  If you have SM capability (or AM
capability and are working on files in your own account), MPEX will
automatically supply the lockword for each file being processed.  This lets you
say something like:

   %RENAME @.OLDGROUP,@.NEWGROUP

without having to specify the lockword of every lockworded file in OLDGROUP.

However, if you execute this %RENAME command, what happens to all the lockwords
of the files being renamed?

Well, remember that we must stay compatible with the MPE :RENAME command.  If
you say (in MPE)

   :RENAME MYFILE/SECRET.OLDGROUP,MYFILE.NEWGROUP

then MYFILE will be renamed from OLDGROUP into NEWGROUP and its lockword will
be removed.  Don't blame us -- this is how MPE does it; if the target filename
does not include a lockword, the new file will be unlockworded.

Therefore, if you say

   %RENAME @.OLDGROUP, @.NEWGROUP

MPEX will interpret this to mean "rename the OLDGROUP files into NEWGROUP and
strip their lockwords" (just like the MPE :RENAME command).

What if you want to keep the lockwords? No problem! Just say

   %RENAME @.OLDGROUP, @/=.NEWGROUP

The "=" in the lockword field means "keep the same lockword as the old file"
(see "Target Filesets" in the MPEX Filesets chapter for more information on
"=").

Therefore, when MPEX issues the :RENAME command for each file in @.OLDGROUP
it'll be certain to include the old file's lockword (if any) on the new
filename.  Instead of saying

   :RENAME MYFILE/SECRET.OLDGROUP,MYFILE.NEWGROUP

it'll say

   :RENAME MYFILE/SECRET.OLDGROUP,MYFILE/SECRET.NEWGROUP

and all the lockwords will be preserved.


_REPEAT______FOREACH_886
%REPEAT ... %FOREACH

Syntax:   %REPEAT
          %>command1
          %>command2
            ...
          %>commandN
          %>FOREACH varname=value[ ,...  ]

Examples: %REPEAT
          %>ECHO Creating group and user for !NAME
          %>NEWGROUP !NAME
          %>NEWUSER !NAME; HOME=!NAME
          %FOREACH NAME=BILL,GEORGE,SUE

The %REPEAT ...  %FOREACH construct performs a sequence of MPEX commands
several times with a given variable (for example, "GROUP") set to each one of a
given list of values:

   %REPEAT
   %>   COPY MYFILE, MYFILE.!GROUP
   %>FOREACH GROUP=PUB,DATA,JOB,LIB

will do the COPY command four times, setting the variable GROUP to the strings
"PUB", "DATA", "JOB", "LIB".  The items on the list can be delimited by commas
or spaces; if an item has an embedded comma or space, enclose it in quotes.


_REPEAT______FORFILES_887
%REPEAT ... %FORFILES

Syntax:   %REPEAT
          %>command1
          %>command2
            ...
          %>commandN
          %>FORFILES fileset[:SPOOL|TEMP]

Examples: %REPEAT
          %>ECHO -----Processing file !MPEXCURRENTFILE
          %>FILE MYFILE=!MPEXCURRENTFILE
          %>RUN MYPROG
          %>FORFILES @.DATA-T@.DATA(NOT ISPRIV)

The %REPEAT ...  %FORFILES construct allows you to execute an arbitrary
sequence of commands on a fileset.  When you type  %REPEAT you wiil be prompted
with  %>

All commands that you type at the "%>" prompts will not be executed as you type
them; instead, they'll be saved up until you type a command such as

   %>FORFILES @.DATA-T@.DATA(NOT ISPRIV)


MPEXCURRENTFILE_888
MPEXCURRENTFILE
("FORFILES" followed by an MPEX fileset).  Then, all the commands you input at
the "%>" prompt will be executed once for each file in the specified MPEX
fileset, with the variable MPEXCURRENTFILE being set in turn to the name of
each file.  For instance, MPEX's fileset %PURGE command might very well be
implemented as something like:

   %REPEAT
   %>:PURGE !MPEXCURRENTFILE
   %>FORFILES fileset

For each file in the fileset, MPEX will execute the MPE command ":PURGE
!MPEXCURRENTFILE".  If we wanted to be more fancy, we could say:

   %REPEAT
   %>ECHO -----Purging !MPEXCURRENTFILE
   %>:PURGE !MPEXCURRENTFILE
   %>FORFILES fileset

In reality, many MPEX commands are actually implemented using the %REPEAT ...
%FORFILES construct.  It is an extremely powerful tool that can let you do
absolutely anything you want (well, almost anything you want) to a fileset.

ACCESSING FILE INFORMATION

As we just mentioned, every time the commands between the %REPEAT and the
%FORFILES are executed, the MPEX variable "MPEXCURRENTFILE" is set to the name
of the current file.  (This is the fully-qualified filename, including the
lockword [if any], group name, and account name.)

However, the filename is not the only piece of information available to you
about the current file.  In fact, all the "FILE ATTRIBUTE VARIABLES" (see "File
Attribute Variables and Functions" in the MPEX Filesets chapter of this manual)
for the current file are available by saying

   RFILE.attrvar

For instance,

   RFILE.CODE            contains the current file's filecode;
   RFILE.FLIMIT          is set to the current file's file limit.

You can access these variables the same way that you access plain MPEX
variables -- in :IFs, in %CALCs, in %SETVARs, and using the "![expression]"
variable substitution construct (see the MPEX Variables chapter for more
information).  For instance, our fileset :PURGE loop might very well look like:

   %REPEAT
   %>ECHO -----Purging !MPEXCURRENTFILE (![RFILE.SECTORS] sectors)
   %>:PURGE !MPEXCURRENTFILE
   %>FORFILES fileset

The string "![RFILE.SECTORS]" will be replaced by the value of the file
attribute variable RFILE.SECTORS, which is the number of sectors the current
file occupies.  You might even say:

   %SETVAR SECTORSSAVED 0
   %REPEAT
   %>ECHO -----Purging !MPEXCURRENTFILE (![RFILE.SECTORS] sectors)
   %>SETVAR SECTORSSAVED SECTORSSAVED+RFILE.SECTORS
   %>:PURGE !MPEXCURRENTFILE
   %>FORFILES fileset
   %ECHO Total: !SECTORSSAVED sectors saved

This uses RFILE.SECTORS in a %SETVAR statement to calculate the total number of
sectors saved by the %PURGE.

One thing to bear in mind is that the values of these RFILE attribute variables
are established only once.  For example, if a file was in use when the fileset
was evaluated, then RFILE.OPENED will be true for that file, even if it has
since been closed.

"FROM" FILESETS AND "TO" FILESETS


OBJECTFILE_889
OBJECTFILE

What about a command like :FCOPY that handles more than one fileset.  The
"from-fileset" would be specified on the %>FORFILES command, and the name of
each from-file would be available as MPEXCURRENTFILE.  What about the
"to-fileset"?

Well, say that we want to copy all files in the fileset "S@.DATA" into files in
the fileset "B@.BACKUP" (i.e.  files with the same name in the BACKUP group,
but with the first S replaced by a B).  We'd do it like this:

   %REPEAT
   %>:FCOPY FROM=!MPEXCURRENTFILE;TO=![OBJECTFILE("B@.BACKUP")];NEW
   %>FORFILES S@.DATA

The new thing here is, of course, the

   ![OBJECTFILE("B@.BACKUP")]

construct.  The "![...]" tells MPEX to execute the expression between brackets
("OBJECTFILE('B@.BACKUP')") and substitute it into the command.


OBJECTFILE_890
OBJECTFILE
OBJECTFILE is a VESOFT function, just like MAX, MIN, STR, UPS, etc.  (please
see Appendix for more information on VESOFT expressions, including functions).
It takes as a parameter an "object fileset" and returns the name of a file in
that fileset that corresponds to the current file in the current fileset.  In
the above example, if

   * the current fileset is S@.DATA, and

   * the current file is SMYPROG.DATA, then

   * OBJECTFILE("B@.BACKUP") will return the string "BMYPROG.BACKUP".

Thus,

   %REPEAT
   %>:FCOPY FROM=!MPEXCURRENTFILE;TO=![OBJECTFILE("B@.BACKUP")];NEW
   %>FORFILES S@.DATA

will execute (for each file in S@.DATA) a command like

   %:FCOPY FROM=SMYPROG.DATA;TO=BMYPROG.BACKUP;NEW

-- just what a normal MPEX

   %FCOPY S@.DATA,B@.BACKUP,NEW

command would do.  In fact, MPEX's %FCOPY command is implemented using a
%REPEAT ...  %>FORFILES loop just like the one above.

RUNNING PROGRAMS AND PASSING THEM INPUT

One thing that you may want to do for each file is to run a program, passing to
it input (perhaps including the current file's name and other attributes).  For
instance, to implement MPEX's %EDIT command, we'd like to %RUN EDITOR.PUB.SYS
for each file and pass it a /TEXT of the current file, a command, and a /KEEP.

The way to do this is to say:

   %REPEAT
   %>RUN EDITOR.PUB.SYS;INPUT="TEXT !MPEXCURRENTFILE";&
   %>    INPUT="the command to be executed";INPUT="KEEP";INPUT="EXIT"
   %>FORFILES fileset

The ;INPUT= keyword causes EDITOR.PUB.SYS to be run with $STDIN redirected to a
temporary disc file to which MPEX has written the values of all the ;INPUT=
strings.

For more information, see the section on the ;INPUT= keyword in the %RUN
command documentation below.

OPERATING ON SPOOL FILESETS


_REPEAT______FORFILES_891
%REPEAT ... %FORFILES
The %REPEAT ...  %FORFILES construct can also be used for performing arbitrary
commands on filesets of spool files.  You must indicate that your fileset is a
spool file fileset by appending a ":SPOOL" to it on the %FORFILES command, i.e.

   %REPEAT
   ...
   %>FORFILES @.@.@(SPOOL.OUTPRI=1):SPOOL


MPEXCURRENTFILE_892
MPEXCURRENTFILE


SPOOL__893
SPOOL.
The commands between the %REPEAT and the %FORFILES will be executed once for
each spool file in the spool file fileset.  The MPEXCURRENTFILE variable will
be set to "#Oxxx" where "xxx" is the spool file number (e.g.  "#O1234"); the
RFILE.attrvar fields will be available just as for normal files, and the spool
file attributes will also be available by saying

   SPOOL.attrvar

(just like file attribute variables except that instead of being prefixed with
"RFILE." they must be prefixed with "SPOOL.").

For example, the following commands will copy all the $STDLISTs in the DEV
account into files in the SAVESP group whose filenames are "STD" followed by
the spool file's spool file number:

   %REPEAT
   %>  RUN SPOOK5.PUB.SYS;&
   %>    INPUT="TEXT !MPEXCURRENTFILE";&
   %>    INPUT="COPY ALL,STD![SPOOL.SPOOLFILENUM].SAVESP";&
   %>    INPUT="QUIT"
   %>FORFILES $STDLIST.@.DEV:SPOOL

OPERATING ON TEMP FILESETS


_REPEAT______FORFILES_894
%REPEAT ... %FORFILES
The %REPEAT ...  %FORFILES construct can also be used for performing arbitrary
commands on filesets of temp files.  You must indicate that your fileset is a
temp fileset by appending a ":TEMP" to it on the %FORFILES command, i.e.

   %REPEAT
   ...
   %>FORFILES @.@.@:TEMP

When operating on temp filesets, the MPEXCURRENTFILE variable contains the
fully qualified name of the current temporary file, but does not indicate in
any way the file is a temp file.  For example, the following is wrong:

   %COMMENT --- Do NOT do this!  This is an example of something that
   %COMMENT --- doesn't work the way you might expect!
   %REPEAT
   %   PURGE !MPEXCURRENTFILE
   %FORFILES @.FOOBAR.PROD:TEMP

This will purge all permanent files in the group FOOBAR.PROD that have the same
name (fully qualified) filename as any of your temp files! What you should do
(in this case) is:

   %COMMENT --- Do this instead.
   %REPEAT
   %   PURGE !MPEXCURRENTFILE,TEMP
   %FORFILES @.FOOBAR.PROD:TEMP

Only use commands that operate on temp files, and use whatever options you
normally need to use to specify temp files.


_REPEAT______FORJOBS_895
%REPEAT ... %FORJOBS

Syntax:   %REPEAT
          %>command1
          %>command2
            ...
          %>commandN
          %>FORJOBS userset

Examples: %REPEAT
          %>ECHO -----Processing job ![RJOB.FMTJOB] ![RJOB.FMTLOGON]
          %>IF RJOB.INPRI=2 THEN
          %>  :ALTJOB ![RJOB.FMTJOB];INPRI=3
          %>ELSE
          %>  :ABORTJOB ![RJOB.FMTJOB]
          %>ENDIF
          %>FORJOBS @.AP&WAIT

Similar to %REPEAT ...  %FORFILES, the %REPEAT ...  %FORJOBS construct allows
you to execute an arbitrary sequence of commands on a VESOFT userset (see the
usersets section of the SECURITY User Manual for details on usersets).


RJOB__896
RJOB.
Note that you can use the RJOB.attrvar syntax to refer to the job attribute
variables of each job much like you can use the RFILE.attrvar syntax in the
%REPEAT ...  %FORFILES construct.  For a list of attributes that can be used
with this syntax,  refer to the section "Job/Session Attributes" in this
manual.


_REPEAT______FORNUM_897
%REPEAT ... %FORNUM

Syntax:   %REPEAT
          %>command1
          %>command2
            ...
          %>commandN
          %>FORNUM varname=startvalue,endvalue[,increment]

Examples: %REPEAT
          %>:BUILD TESTDAT!I; REC=-80,,F,ASCII
          %>FORNUM I=1,9

The %REPEAT ...  %FORNUM construct is just like the FOR in C/PASCAL/SPL,
PERFORM VARYING in COBOL, and DO in FORTRAN:

   %REPEAT
   %>:ABORTJOB #J!I
   %>FORNUM I=955,970

will execute the %ABORTJOB sixteen times, setting the variable I to numbers
from 955 to 970.  To increment I by a value other than 1 for each iteration,
just say

   %FORNUM I=startvalue,endvalue,increment

(e.g.  %FORNUM I=0,100,10 will set I to 0, 10, 20, 30, ..., 100.)


_REPEAT______FORPROFILES_898
%REPEAT ... %FORPROFILES

Syntax:   %REPEAT
          %>command1
          %>command2
            ...
          %>commandN
          %>FORPROFILES profileset

NOTE: This repeat construct requires SECURITY/3000 to be active.

MPEX's %REPEAT ...  %FORPROFILES construct allows you to perform an arbitrary
set of actions on SECURITY profiles.  Although the %SEC CHANGE command lets you
change large groups of profiles, and the %SEC LISTUSER lets you report on any
set of profiles, there are still some limitations to these commands.  The %SEC
CHANGE command is limited to changing ALL the profiles in the profileset to
have the SAME value, and the %SEC LISTUSER command displays profiles with only
one format.

Using %REPEAT ...  %FORPROFILES, however, you can change fields of each profile
that qualifies with different values (which may even be based upon current
values of other fields).  Simple reports can be generated by using the %ECHO
command to format and display the values of any field within the profile.

Within the loop itself, profile field values are referenced using the same
syntax as in %REPEAT ...  %FORFILES, namely, use ![PROFILE.attribute] as part
of the command (refer to the USER PROFILE ATTRIBUTES chapter of the SECURITY
manual for a description of these attributes).  The variable MPEXCURRENTPROFILE
will contain the key value for the current profile, in session,user.account
format, for use in a %SEC CHANGE command.

For example, lets say you have a user defined field that contains a three-digit
department code and you want to change them to be four-digits by adding a "1"
to the beginning of each code.  The following %REPEAT ...  %FORPROFILES loop
will do just that:

   %REPEAT
      %SEC CHANGE !MPEXCURRENTPROFILE;DEPT=!["1"+PROFILE.UF('DEPT')]
   %FORPROFILES @,@.@(UF('DEPT')<>'')


_REPEAT______FORRECS_899
%REPEAT ... %FORRECS

Syntax:   %REPEAT
          %>command1
          %>command2
            ...
          %>commandN
          %>FORRECS varname=fopenparms

Examples: %REPEAT
          %>RUN MYPROG1; INPUT=PROCDATE
          %>FILE DATAFILE=D!PROCDATE.DATA
          %>RUN MYPROG2
          %>FORRECS PROCDATE=MYFILE,OLD

The %REPEAT ...  %FORRECS construct performs a sequence of MPEX commands once
for each record of a given file, with a given variable (for example,
"CURRENTREC") set to each record of the file:

   %REPEAT
   %>ECHO Processing !CURRENTREC
   %>RUN MYPROG;INFO="!CURRENTREC"
   %>FORRECS CURRENTREC=DATAFILE,OLD

will do the commands between "%REPEAT" and "%FORRECS" once for each record in
the file DATAFILE, setting the variable CURRENTREC to the contents of the
current record.


_RESUMEJOB_900
%RESUMEJOB

Syntax:   %RESUMEJOB [userset]
          [;NOVERIFY]
          [;QUIET]

Examples: %RESUMEJOB @.AP
          %RESUMEJOB
          %RESUMEJOB REPORTJ,@.@
          %RESUMEJOB #J1234+#J1235

The %RESUMEJOB command is an enhanced version of MPE's :RESUMEJOB command.  It
allows you to specify which jobs to resume using VESOFT usersets (see the
usersets section of the SECURITY User Manual).  By default, the userset is
"SUSP", or all suspended jobs (in fact, "&SUSP" is appended to the userset
supplied since it doesn't make sense to try and :RESUMEJOB a job that is not
suspended).


_RETURN_901
%RETURN

Syntax:   %RETURN

Examples: << sample MPEX command file: >>
          PARM FILE, OP
          IF NOT FEXISTS("!FILE") THEN
             ECHO Error: !FILE does not exist.
             RETURN
          ENDIF
          ...

The %RETURN command exits the currently-executing UDC or command file; in the
example above, it's used to exit a command file in case the FILE parameter
turns out to be invalid.  This sort of thing -- exiting command files and UDCs
in case of an error condition -- is what %RETURN is most often used for.


_RUN_902
%RUN


NOACTSONTERM_903
NOACTSONTERM

Syntax:   %RUN progfile|pin [,entry]
          [;mperunparms]
          [;GOON]
          [;INMSG]
          [;INPUT= inline] [;INPUT= ...  ]
          [;KILL]
          [;NEW]
          [;NOACTIVATE]
          [;NOACTSONTERM]
          [;PRI= CS|DS|ES]
          [;STDIN= fileref|$NULL|"file-eq-parms"
          [;STDLIST= fileref|$NULL|"file-eq-parms"

Examples: %RUN MYPROG; MAXDATA=30000; LIB=G
          %RUN BIGHOG; PRI=ES; GOON
          %RUN SPOOK5.PUB.SYS; NOACTIVATE
          %RUN MYPROG; STDIN="TEMPMSG;REC=,,V,ASCII;DEL";&
                       STDLIST="OUTFILE,OLDTEMP;SHR;GMULTI;TEMP"
          %RUN SEGDVR.PUB.SYS; INPUT="USL U"; INPUT="AUXUSL AU";&
                               INPUT="COPY SEGMENT,MYSG"; INPUT="EXIT"

MPEX's %RUN command fully emulates all the parameters of the MPE :RUN command
(;LIB=, ;PARM=, ;INFO=, ;MAXDATA=, etc.), and implements a few of its own (see
"MPEX Process Handling" in the MPEX Special Topics chapter for more information
-- these features are fairly advanced, and are probably not for beginning
users):

   * ;PRI=CS|DS|ES, which lets you indicate the queue in which the son
     process is to run (just like the ;PRI= parameter on a :JOB card works for
     a job).

   * ;GOON ("go on"), which means that MPEX shouldn't suspend when it creates
     the son process, but rather go on processing with both MPEX and the son
     being active.

   * ;NOACTSONTERM, which means that MPEX should not be automatically
     reactivated when the son process terminates.  This can sometimes be useful
     in conjunction with the ;GOON keyword; however, if you use ;NOACTSONTERM
     without using ;GOON, you're liable to get hung up when the son process
     terminates and does not reactivate MPEX.

   * ;STDIN/STDLIST="parms", which let you specify not just the filename for
     the son's $STDIN/$STDLIST, but a full :FILE-equation (except for the word
     FILE), including options such as ;DEL, ;SHR, ;REC=, etc.  Note: see
     "Command I/O Redirection" for information on another way to re-direct
     $STDIN/$STDLIST.

   * ;INPUT= (and ;INMSG), which let you pass data as input to the son process
     without building a special $STDIN file.  MPEX will build the $STDIN file
     for you, writing the values of all the ;INPUT= parameters to it; the son
     process will then be run with that $STDIN file.  (See also "%RUNCREATE,
     %RUNINPUT, %RUNACTIVATE", below).

   * ;NOACTIVATE, which creates the son process without activating it.

   * ;NEW, which commands MPEX to create a new process, even if another son
     process with the same name exists and is ready to be reactivated.

   * ;KILL, which tells MPEX to kill the son process when it's done (in case it
     suspends rather than terminates).

   * Instead of specifying the name of the program to be run, you may specify
     the PIN of an already existing son process; in that case, that process
     will be reactivated.


Automatic_lockword_insertion_for__RUN_commands_904
Automatic lockword insertion for %RUN commands
   * If you have SM capability, or are AM of the account in which the program
     you are %RUNing resides, and the program file has a lockword, MPEX will
     automatically insert the lockword for you.


_RUNCREATE_905
%RUNCREATE


_RUNINPUT_906
%RUNINPUT


_RUNACTIVATE_907
%RUNACTIVATE

Syntax:   %RUNCREATE program [,entry] [;mpexrunparms]

          %RUNINPUT inputline

          %RUNACTIVATE

Examples: %RUNCREATE MYPROG,PROCFILES; PARM=1; PRI=CS
          %REPEAT
          %>RUNINPUT !MPEXCURRENTFILE
          %>FORFILES @.DATA
          %RUNINPUT EXIT
          %RUNACTIVATE


_INPUT__908
;INPUT=
MPEX's %RUN ;INPUT= lets you run a program and pass input lines to it (without
having to specially build a ;STDIN= file).  What if, however, you want to pass
many input lines (more than can fit on one %RUN command)? This is particularly
relevant for %REPEAT ...  %FORFILES, with which you might want to pass a
program one or more lines of input for each file in the fileset.

MPEX's %RUNCREATE, %RUNINPUT, and %RUNACTIVATE commands let you do this --
%RUNCREATE creates a son process but doesn't actually run it; %RUNINPUT writes
a line of input to its ;STDIN= file; %RUNACTIVATE actually activates it and
waits for it to finish executing all the commands you passed to it using
%RUNINPUT.

For instance,

   %RUNCREATE KSAMUTIL.PUB.SYS
   %REPEAT
   %>RUNINPUT KEYINFO !MPEXCURRENTFILE
   %>FORFILES @.@.AP(ISKSAM and NOT ISKSAMXL)
   %RUNINPUT EXIT
   %RUNACTIVATE

This will run KSAMUTIL.PUB.SYS, pass it a KEYINFO command for each file in the
fileset (which automatically recovers any KSAM files that were open during a
system failure), and then an EXIT command, and finally activate
KSAMUTIL.PUB.SYS to let it execute all those commands.

Note that the program is not activated until the %RUNACTIVATE -- the %RUNINPUT
commands don't actually "execute" the commands but rather buffer them up in the
son process' STDIN= file to be executed when the %RUNACTIVATE is done.  The
%RUNCREATE, %RUNINPUT, and %RUNACTIVATE are actually shorthand ways to say
"%RUN progname;NOACTIVATE;NEW;INMSG", "%RUN progname;INPUT=", and "%RUN
progname;KILL" respectively -- all of which are documented MPEX enhancements to
the :RUN command.

One important point about these commands is the fact that they use a message
file to pass your input to the program being run.  If you forget to %RUNINPUT
an EXIT command of some sort, then the program will merely suspend after it is
done executing the commands you gave it instead of terminating (This is similar
to how the %SPOONFEED command works).  The problem that this creates is that
control is never returned to MPEX, so it appears that our program hangs.  You
should press [BREAK] and type :ABORT to terminate MPEX and the "suspended"
program.


_SAVEJOB_909
%SAVEJOB

Syntax:   %SAVEJOB userset; FILE=savefile
          [;NOVERIFY]
          [;QUIET]

Syntax:   %SHOWSAVED; FILE= savefile

Syntax:   %DOSAVED;FILE=savefile
          [;NOVERIFY]
          [;QUIET]
          [;MUSTEXEC]
          [;mpeschedparms]

Examples:  %SAVEJOB WAIT+SCHED; FILE=SAVEDJBS
           %SAVEJOB @.PROD; FILE=PRODJOBS; NOVERIFY
           %SAVEJOB @.@-EXEC; FILE=ALLJOBS; QUIET
           %SAVEJOB #J1234+#J1235+#J1236; FILE=CRITJOBS

           %SHOWSAVED;FILE=PRODJOBS

           %DOSAVED;FILE=SAVEDJBS
           %DOSAVED;FILE=PRODJOBS; NOVERIFY; AT=23:30
           %DOSAVED;FILE=ALLJOBS; QUIET; MUSTEXEC
           %DOSAVED;FILE=CRITJOBS; IN=0,0,5

   Note: for security reasons, this command can only be executed by users who
         have SM capability.


MPE_V_and_MPE_iX_differences___SAVEJOB_command_910
MPE/V and MPE/iX differences: %SAVEJOB command
         Due to MPE/V limitations, this command is only available on MPE/iX
         systems.

You need to shut your system down, but there are a bunch of jobs in the WAIT
and SCHED state.  What do you do?

You could try writing down the names of all of the jobs and then re-:STREAM
them after you bring the system back up, but the :SHOWJOB command only shows
you how the job logs on, not the name of the file that was :STREAMed (sometimes
they match, but...).  What if the job file doesn't even exist anymore? If you
use STREAMX, how are you going to know what answers were entered to any
::PROMPTs the jobs contain?

The %SAVEJOB command saves the $STDIN files for all (or selected) jobs, so that
you can later re-submit them via the %DOSAVED command (described below)! Since
the $STDIN file -- not the job file -- is what MPE actually executes, the saved
job (when re-submitted later) will be exactly the same (except for the job
number) as it was before you saved it:

   * all of the job-card parameters (like ;INPRI=, etc.) will be preserved;

   * if you use SECURITY, any necessary $BATCH-VEPROFILE job authorizations
     will still be in effect;

   * all STREAMX parameter substitutions were done before the $STDIN was
     created, so they won't be lost;

   * if the job was in a SCHED state at the time it was saved, the scheduling
     information will also be preserved.

Here's how it works:

   %SAVEJOB WAIT+SCHED; FILE=SAVEDJBS
   -----Will SAVEJOB #J41, DISCLEAN,MANAGER.SYS,JOB
   -----Will SAVEJOB #J38, SEND,MANAGER.LIST,VESOFT
   -----Will SAVEJOB #J33, VEADIT,MANAGER.VESOFT,PUB
   -----Will SAVEJOB #J34, NIGHTLY,MGR.PROD,PUB
   OK to process these jobs (y/n)? Y
   -----SAVEJOB #J41, DISCLEAN,MANAGER.SYS,JOB
   -----SAVEJOB #J38, SEND,MANAGER.LIST,VESOFT
   -----SAVEJOB #J33, VEADIT,MANAGER.VESOFT,PUB
   -----SAVEJOB #J34, NIGHTLY,MGR.PROD,PUB

Like the %ABORTJOB, %TELL, %ALTSCHED, and other MPEX jobset-handling commands,
%SAVEJOB allows you to specify which job(s) to save using VESOFT usersets
(documented fully in the usersets section of the SECURITY User Manual).

If you want %SAVEJOB to save the jobs without asking you if it's OK, use the
;NOVERIFY keyword.

If you don't even want %SAVEJOB to show you the jobs as it saves them, use the
;QUIET keyword.

At this point, you can shut down your system, or perhaps abort these jobs via
the MPEX %ABORTJOB command (%SAVEJOB does not abort the existing job) and wait
for the currently executing jobs to finish before shutting down.

VIEWING SAVED JOBS (%SHOWSAVED)

%SAVEJOB copies the jobs to the "savefile" in a special format (and creates the
"savefile" as a PRIV file -- you must use MPEX to %PURGE it).  To see what jobs
are in a "savefile", use the %SHOWSAVED command:

   %SHOWSAVED;FILE=SAVEDJBS
   :JOB DISCLEAN,MANAGER.SYS,JOB;PRI=DS;OUTCLASS=LP,3,1
          DATE=01/29/92;AT=03:00
   :JOB SEND,MANAGER.LIST,VESOFT;HIPRI;PRI=CS;OUTCLASS=LP,2,1
          DATE=01/29/92;AT=02:30
   :JOB VEADIT,MANAGER.VESOFT,PUB;PRI=DS;OUTCLASS=LP,1,1
          DATE=01/29/92;AT=22:00
   :JOB NIGHTLY,MGR.PROD,PUB;HIPRI;PRI=DS;OUTCLASS=LP,1,1
          DATE=01/29/92;AT=00:01

RE-SUBMITTING SAVED JOBS (%DOSAVED)

After you bring the system back up (or whenever you like) you can re-submit
saved jobs by typing:

   %DOSAVED;FILE=SAVEDJBS

By default, this will display the job logon and scheduling parms (if any) for
each job in the SAVEDJBS file, and ask if you want to submit that job:

   Submit DISCLEAN,MANAGER.SYS,JOB [date=01/29/92;at=03:00] (y/n)? Y
    #J54
   Submit SEND,MANAGER.LIST,VESOFT [date=01/29/92;at=02:30] (y/n)? Y
    #J55
   Submit VEADIT,MANAGER.VESOFT,PUB [date=01/29/92;at=22:00] (y/n)? Y
    #J56
   Submit NIGHTLY,MGR.PROD,PUB [date=01/29/92;at=00:01] (y/n)? N

Like %SAVEJOB, you can use the ;NOVERIFY to submit job(s) without prompting, or
;QUIET to submit them without even listing them.

When you re-submit saved jobs, %DOSAVED simply re-submits the jobs with the
originally scheduled date and time.  Generally, this is OK; however, you may
end up in the situation where a saved job was scheduled to run specifically at
a time when the jobs were not on the system (i.e., if you had to take the
system down, and a job was scheduled to run during the time the system was
down).  In this case, an error message is displayed regarding an attempt to
stream a job prior to the current date and time.


_MUSTEXEC_911
;MUSTEXEC
There are two methods you can use to avoid this problem.  Either specify the
keyword ;MUSTEXEC, which signals to our software that if the time for a job to
launch has passed, stream the job immediately.  The other method is to supply
new scheduling parameters with the %DOSAVED command (like ;AT=, ;DAY=, ;DATE=,
or ;IN=) to override those that were in effect when the job was saved; e.g.

   %DOSAVED;FILE=SAVEDJBS; DATE=01/31/92
   Submit DISCLEAN,MANAGER.SYS,JOB [date=01/31/92] (Y/n)? N
   Submit SEND,MANAGER.LIST,VESOFT [date=01/31/92] (Y/n)? N
   Submit VEADIT,MANAGER.VESOFT,PUB [date=01/31/92] (Y/n)? N
   Submit NIGHTLY,MGR.PROD,PUB [date=01/31/92] (Y/n)? Y
    #J58

Any scheduling parameters specified with %DOSAVED will completely replace all
scheduling parameters that were "saved" with the job; if the job was not
scheduled when it was saved (i.e.  it wasn't in a SCHED state), the %DOSAVED
scheduling parms will not be applied to it.

If you want to PURGE the savefile (%DOSAVED does not automatically PURGE it),
simply use the MPEX %PURGE command -- MPE's :PURGE command doesn't purge PRIV
files.

IMPORTANT NOTE: There is no need to save schedule if you use STREAMX's
scheduling -- see the SECURITY User Manual for details.


_SCHEDULE_912
%SCHEDULE


Batch_execution_of_MPEX_commands___SCHEDULE_913
Batch execution of MPEX commands: %SCHEDULE

Syntax:   %SCHEDULE "scheduleparms", "[joblogon] [;jobparms]", command

Examples: %SCHEDULE "AT=3:00;DAY=TUE",, COBOL AP@.SOURCE, AP@.PUB
          %SCHEDULE "AT=21:00", ";OUTCLASS=,3", RUN MYPROG;PARM=1234
          %SCHEDULE "AT=1:00", "MANAGER.SYS", PURGE LOG####.PUB.SYS

The %SCHEDULE command makes MPEX submit a scheduled job that will execute the
given MPEX command.

   * You can use any MPE scheduling parameters (AT=, DAY=, etc.).


_SCHEDULE_and_STREAMX_scheduled_jobs__914
%SCHEDULE and STREAMX scheduled jobs
   * You may use our extensions to MPE's scheduling parameters to cause the job
     to repeat on a regular basis (see the Scheduling STREAMX jobs to repeat in
     the SECURITY manual).

   * You may (optionally) indicate that the job is to be submitted under
     somebody else's user ID or with some special job parameters.

   * You may execute either an MPEX command or a normal MPE command (RUN,
     STORE, a UDC, etc.); if the MPE command has the same name as an MPEX
     command (like FCOPY), precede it with  a ":".

   * All the file equations that are in effect in your session, and the current
     value of your HPPATH variable, will automatically be copied to the created
     job.

   * You may indicate who MPEX should notify of the job's completion by setting
     the MPEXTELLBACK variable.

   * You may indicate how MPEX should inform you of the job's completion by
     setting the MPEXTELLBACKCMD variable.

(See the %SUBMIT and "Batch Execution ('$' Prefix)" in the MPEX Commands
chapter for more information.)

To execute an MPEX command in a job stream, you can simply say

   %$COBOL AP@.SOURCE, AP@.PUB

The "$" tells MPEX to perform the command offline -- MPEX will automatically
generate a job stream that executes the above command.

It'll also copy all the :FILE-equations (such as :FILE COPYLIB=...) that you
may have in your session into the job, so that the job environment is as close
as possible to your session environment.

The %SCHEDULE command simply extends this capability to allow you to specify
scheduling and :JOB card parameters for the job stream.  Saying

   %$COBOL AP@.SOURCE, AP@.PUB

will execute "COBOL AP@.SOURCE, AP@.PUB"

   * immediately,

   * under your own logon id,

   * with the job parameters ";OUTCLASS=,1".

What if you want to submit it at 3 AM Tuesday? Just say:

   %SCHEDULE "AT=3:00;DAY=TUE",, COBOL AP@.SOURCE, AP@.PUB

The first parameter ("AT=3:00;DAY=TUE") specifies the :STREAM command
scheduling parameters; since the second parameter is omitted, the logon ID and
job parameters will be the default.

If you say

   %SCHEDULE "AT=3:00;DAY=TUE", "MGR.PROD;OUTCLASS=SLOWLP,3", &
             COBOL AP@.SOURCE, AP@.PUB

then it'll not only define the scheduling parameters but also the logon
(MGR.PROD) and job card parameters (;OUTCLASS=SLOWLP,3).  Saying

   %SCHEDULE "AT=3:00;DAY=TUE", ";OUTCLASS=SLOWLP,3;INPRI=4", &
             COBOL AP@.SOURCE, AP@.PUB

will only change the job card parameters (;OUTCLASS=SLOWLP,3;INPRI=4); the
logon will be the default (your own logon ID).  Saying

   %SCHEDULE "AT=3:00;DAY=TUE", "MGR.PROD", COBOL AP@.SOURCE, AP@.PUB

will only change the logon ID (MGR.PROD) and leave the job card parameters at
their default setting (;OUTCLASS=,1).

Of course, if you try to submit something under somebody else's logon ID, MPEX
will prompt you for the passwords (unless you have SM capability, or AM
capability in your own account).


_SEC_915
%SEC

Syntax:   %SEC command

Examples: %SEC LISTUSER @.@
          %SEC ADD JAY,MGR.SALES; ASKPASS

The %SEC prefix allows SECURITY users to enter SECURITY maintenance commands
within MPEX.  Please see "Command-Driven SECURITY Maintenance" in the
SECURITY User Manual for details.


_SECURE_916
%SECURE


IMAGE_databases__securing_917
IMAGE databases: securing

Syntax:   %SECURE fileset
          [;KEEPAMDATES]

Examples: %SECURE @.@.PROD-TEST@.@.PROD(ISRELEASED)
          %SECURE @.@.@ &
                  (ISPROG and ISRELEASED and DIRGROUP.CAP("PM"))

The MPEX %SECURE command lets you

   * %SECURE entire filesets

   * even if you're not the file's creator (all it takes is Read, Write, and
     eXecute access -- since with Read, Write, and eXecute, you can do anything
     to the file [including purging it], this is quite safe); additionally,


KEEPAMDATES_918
KEEPAMDATES
   * the ;KEEPAMDATES keyword allows you to secure a file (or fileset) without
     changing that file's last Access and Modify dates.

As you know, :RELEASEing a file is very dangerous to system security.  When you
:RELEASE a file, you are letting anybody do anything to it -- read it, write to
it, even purge it! There's no way of :RELEASEing a file for read access only,
or to a particular user or set of users.

If you :RELEASE a (non-privileged) file, you lose absolutely all security with
respect to it.

This is why the %SECURE command can be so useful.  Chances are that there are
hundreds of :RELEASEd files on your system, :RELEASEd from ignorance (most
people don't know how wide-open the :RELEASE command leaves them) or laziness.

The only way you can %SECURE them all in one fell swoop is with MPEX.  You
could always find them with the %LISTF command:

   %LISTF @.@.PROD(ISRELEASED)

but you could always just :SECURE them all:

   %SECURE @.@.PROD(ISRELEASED)

(the ISRELEASED selection condition will find only those files that are
actually :RELEASEd, and thus avoid re-:SECUREing files that are already
:SECUREd).

If for some reason, you need some files to remain :RELEASEd, you can easily
tailor your selection conditions to exclude them from the %SECURE:

   %SECURE @.@.PROD-TEST@.@.PROD(ISRELEASED and NOT ISPRIV)

will :SECURE all the :RELEASEd files in the PROD account EXCEPT for databases
(NOT ISPRIV) and those files that start with TEST.  (As we discuss in the
%RELEASE command, databases are the only files that it's often a good idea to
:RELEASE.)

***VITAL FOR SYSTEM SECURITY!***

There's one very important way in which :RELEASEd files can

ENTIRELY COMPROMISE YOUR SYSTEM SECURITY.

If you have any

   * program files

   * that are :RELEASEd

   * and reside in groups that have PM capability,

then

   ANY USER -- WITHOUT ANY SPECIAL CAPABILITIES -- WILL BE ABLE TO ACQUIRE SM
   CAPABILITY!

For obvious reasons, we won't tell you how he could do this; however, it's
vital that all the files that match the conditions shown above must be :SECUREd
(with NO exceptions).  With MPEX, nothing could be easier:

   %SECURE @.@.@(ISPROG and ISRELEASED and DIRGROUP.CAP("PM"))

Just another example of the power of MPEX selection conditions.


_SET_CAPABILITY__919
%SET CAPABILITY

Syntax:   %SET CAPABILITY,command,SM|AM|AL

Examples: %SET CAPABILITY,PURGE,AM
          %SET CAPABILITY,RELEASE,SM

MPEX does not in any way endanger your system security -- anything "dangerous"
you could do in MPEX can be done with simple MPE commands (although it would
take longer!).

However, when MPEX makes it easier for you to do some things, it has no way of
knowing that what you ask it to do is what you really want it to do.  If you
say

   %RELEASE @

MPEX will faithfully :RELEASE all the files in your group (assuming you have
Read/Write/Execute access to the files).  Never mind the fact that this will
remove ALL security from those files -- you asked it to :RELEASE them, and
that's exactly what it'll do.

Because of this, a system manager might want to restrict access to some MPEX
commands -- usually %PURGE and %RELEASE -- to people with certain capabilities.
For instance, he might put into the MPEXMGR.PUB.VESOFT file (which always gets
executed whenever anybody enters MPEX -- see "Specifying Commands To Be
Executed Every Time MPEX Is Entered" in the Running MPEX section) the commands:

   %SET CAPABILITY,PURGE,AM
   %SET CAPABILITY,RELEASE,SM

This means that

   * Only users with SM capability will be allowed to use the %RELEASE command.

   * Only users with AM capability will be allowed to use the %PURGE command.
     Users with AM only will be able to %PURGE files only in their own accounts
     -- users with SM will be able to %PURGE files anywhere.

The capabilities that you can specify are SM, AM, or AL (Account Librarian).

We advise, however, that you use %SET CAPABILITY sparingly; naturally, we think
that most MPEX commands are just too useful to deny access to.  Please see the
chapter on "Restricting MPEX Commands To Only Work On Certain Files" in the
Running MPEX section in this manual.  There, we explain how you can set up your
own commands with your own restrictions -- for instance, you could easily build
a %PURGE that will not purge databases or KSAM files, or an %ALTFILE that will
only work for files in your logon group.


_SET_CREATORPROTECT__920
%SET CREATORPROTECT

Syntax:   %SET CREATORPROTECT

MPEX's %ALTFILE ;CREATOR= and %COPY ;CREATOR= keywords let you change a file's
creator ID.  This can be a very useful feature (see the documentation on
%ALTFILE ;CREATOR= for more information) in many instances, including changing
the creator IDs of files whose creators have been purged.  Normally (on
non-POSIX systems), MPEX allows anybody who has Read, Write, and eXecute access
to a file to %ALTFILE its creator ID, since with that sort of access the user
can do anything to the file anyway.

Some users need creator IDs for their own internal auditing purposes and
therefore don't want to let people change files' creator IDs.  The %SET
CREATORPROTECT command lets system managers impose this restriction if they so
wish.

If you put a "SET CREATORPROTECT" command into your MPEXMGR.PUB.VESOFT (see
"Specifying Commands To Be Executed Every Time MPEX Is Entered" in the Running
MPEX section), then only users with SM capability and users with AM capability
working on files in their own accounts will be allowed to do an %ALTFILE
;CREATOR= or a %COPY ;CREATOR= (of course, non SM/AM users can still use any of
the other %ALTFILE and %COPY keywords).  Also, if any non-SM non-AM user uses
the %COPY ;KEEPATTR command, the creator ID will not be kept by the copy, but
will instead be set to the copying user's name.

%SET CREATORPROTECT will still permit SM users and AM users working on files in
their own accounts to use %ALTFILE ;CREATOR=, %COPY ;CREATOR=, and %COPY
;KEEPATTR without restriction.

POSIX NOTE:    Due to changes in MPE regarding file security, MPEX enforces
               %SET CREATORPROTECT on POSIX based systems.  This is to maintain
               compatibility with MPE's :ALTFILE command which is designed to
               let SM and AM users change the OWNER of a file.  See the
               %ALTFILE command for more details.


_SET_DATE__921
%SET DATE

Syntax:   %SET DATE,MDY|DMY|YMD

Examples: %SET DATE,MDY

By default, MPEX dates -- in selection conditions, in the %CALC, :IF, %SETVAR,
etc.  commands, and so on -- are expected to be in MM/DD/[YY]YY (2- or 4-digit
year, with or without slashes) format.  You can change this by saying

   %SET DATE,DMY

to indicate that input dates will be in DD/MM/[YY]YY format, or

   %SET DATE,YMD

to indicate that input dates will be in [YY]YY/MM/DD format.

Note that while most commands do not make use of this setting to determine how
to display date values, a few commands do use this setting.  The commands that
do make use of this setting have a note to that effect in their command
description.  If you want to output a date in a specific format (in a %CALC
command or your own %LISTF template file), you can use the CDATEMDY, CDATEDMY,
and CDATEYMD functions or the built-in formatting capability of the WRITELN and
STRWRITE functions.  (see Appendix for more details).


_SET_DEFAULT__922
%SET DEFAULT

Syntax:   %SET DEFAULT,command,?|!|$

Examples: %SET DEFAULT,PURGE,?
          %SET DEFAULT,COBOL,$

By default, all MPEX commands are executed online, immediately as you type
them.  You can always prefix any MPEX command with a "$", e.g.

   %$COBOL AP@.SOURCE,AP@.PUB

to perform it offline, or prefix it with a "?", e.g.

   %?PURGE @.TEST

to verify the %PURGE for every file before purging that file (MPEX will ask you
"OK to process X.TEST (y/N)? ", and if you answer N, the operation won't be
done on this file).

You might want to make either "$" execution or "?" execution the default for
some commands; for instance,

   %SET DEFAULT,PURGE,?
   %SET DEFAULT,COBOL,$

to indicate that all %PURGEs are to be done with verification (for safety's
sake) and all %COBOLs are to be done offline (to avoid tying up your terminal).
When these defaults are set, you can still say

   %!PURGE K#######.@
   %!COBOL AP010.SOURCE,AP010.PUB

to execute the commands ONLINE with no verification (that's what the "!" prefix
does); however, the DEFAULT will be "?" for %PURGE and "$" for %COBOL.

Remember, in all cases you can execute each command any way you like (online,
offline, or with verification) with one extra keystroke; %SET DEFAULT merely
indicates which mode is to be used if you specify neither "!", "?", nor "$".

If you use the %SET DEFAULT command, you'll probably want to embed it into

   * the MPEXMGR.PUB.VESOFT file, so it'll be automatically executed every time
     anybody runs MPEX (and will thus be in effect on a SYSTEM-wide basis),

   * the MPEXMGR.PUB file of your own account, so it'll be automatically
     executed every time anybody in that account runs MPEX, and/or

   * the MPEXMGR file of your own group, so it'll be automatically executed
     every time anybody in that group runs MPEX.

See "Specifying Commands To Be Executed Every Time MPEX Is Entered" in the
Running MPEX section for more information.


_SET_GOONMAXPRI__923
%SET GOONMAXPRI

Syntax:   %SET GOONMAXPRI,CS|DS|ES

Examples: %SET GOONMAXPRI,CS
          %SET GOONMAXPRI,ES

The %GOON command (documented earlier in this manual) gives MPEX users an easy,
convenient way to execute commands, run programs, etc.  as son processes.  By
default, %GOON processes execute in the DS queue (which gives them about the
same priority as batch jobs, on most systems) but users may change this by
setting the VESOFTGOONPRI variable.

Although this doesn't allow users to do anything that MPE security would
normally prevent them from doing, it does make it much easier for one user to
create many active son processes in the CS queue.  The system manager might
wish to restrict %GOON processes to the DS (or even the ES) queue.

To do this, simply add a line to your MPEXMGR.PUB.VESOFT file that says
something like:

   %SET GOONMAXPRI,DS

Now, even if the user sets the VESOFTGOONPRI variable to "CS", his %GOON
processes will run in the DS queue.

Note that once a %SET GOONMAXPRI command has been executed within your current
run of MPEX, you can not change it to a lower queue until you exit MPEX and
re-run it; i.e.  if you set the max.  pri.  to DS (as in the example above),
you will not be able to change it back to CS unless you first exit MPEX (but
you could change it to ES).


_SET__NO_CHLOGONRETURN__924
%SET [NO]CHLOGONRETURN

Syntax:   %SET [NO]CHLOGONRETURN

Examples: %SET CHLOGONRETURN
          %SET NOCHLOGONRETURN   (* SM users only *)

If you use the %CHLOGON command on MPE/iX, and then exit from MPEX, you will
automatically be switched back to your original logon.  On MPE/V, however, you
will (by default) not be switched back.  (The reasons for this are discussed in
detail in the %CHLOGON chapter earlier in this manual.)

If you want MPEX to automatically switch you back to your original logon when
you exit on MPE/V, simply do a

   %SET CHLOGONRETURN

You may even choose to put this command in your MPEXMGR.PUB.VESOFT file, to set
this option permanently for all users.

For security reasons (because this option affects what UDCs may be in effect
when you exit from MPEX -- see %CHLOGON for details) normal users can not unset
this option after it has been set.  SM users, however, may do a

   %SET NOCHLOGONRETURN

to unset the option.


_SET__NO_CMDTRACECHECK__925
%SET [NO]CMDTRACECHECK

Syntax:   %SET [NO]CMDTRACECHECK

Examples: %SET CMDTRACECHECK
          %SETJCW MPEXCMDTRACE = 1

MPEX, STREAMX, and VEMENU all let you trace execution of commands using the
MPEXCMDTRACE JCW; if you set it to 1, each command is output before it is
executed, which can help you debug complicated command files, job streams, or
menus.

It takes time to check this variable and this can add up if you have a very
complicated command file or menu (one of our users sent us a menu file that had
about 100 lines per caption!), especially if you are on a heavily loaded
system.

Therefore, we have two commands, usable from MPEX, STREAMX, or VEMENU -- SET
NOCMDTRACECHECK, which turns off MPEXCMDTRACE checking, and SET CMDTRACECHECK,
which turns it on.  Checking is on by default for MPEX and off by default for
STREAMX and VEMENU, but these SET commands can be used to alter this setting.


_SET__NO_VARTRACE__926
%SET [NO]VARTRACE

Syntax:   %SET [NO]VARTRACE

Examples: %SET VARTRACE
          %XEQ MYCMDFIL
          %SET NOVARTRACE

You can write MPEX command files that do a lot of different things (our users
constantly surprise us with the creative use to which they put our software).
The %SET VARTRACE command was implemented to help you debug these command
files.

%SET VARTRACE tells MPEX to echo to $STDLIST the name of any variable whose
value changes, the old and new values of that variable, and the name of the
command file or UDC which changed it ($STDIN, if the variable was changed by an
interactive command).

Using %SET VARTRACE is much easier than adding a bunch of "ECHO" commands to
the command file, and it shows all variables that are changed (including
"local" variables), not just the ones you thought to "ECHO".

%SET NOVARTRACE turns the tracing off.

For example, suppose you have a command file named TEST.WORK.VESOFT that looks
like this:

   SETVAR TEST_VAR "tadpole"
   SETVAR TEST_VAR "frog"
   SETLVAR TEST_LOCAL_VAR "caterpillar"
   SETLVAR TEST_LOCAL_VAR "butterfly"

You could watch these variables change using %SET VARTRACE, like this:

%SET VARTRACE
%TEST
[TEST.WORK.VESOFT]   TEST_VAR := tadpole
[TEST.WORK.VESOFT]   TEST_VAR (tadpole) := frog
[TEST.WORK.VESOFT]   TEST_LOCAL_VAR [local] := caterpillar
[TEST.WORK.VESOFT]   TEST_LOCAL_VAR [local] (caterpillar) := butterfly
%SET NOVARTRACE


_SET_command____MPE_iX_emulation__927
%SET command -- MPE/iX emulation

Syntax:   %SET [STDLIST=DELETE|SAVE]
               [;ECHO=ON|OFF]
               [;MSG=ON|OFF]
               [;SPEED=speed]

Examples: %SET ECHO=OFF;MSG=OFF
          %SET SPEED=300

Note: Also see the other %SET commands documented above.

Any of the options that are permitted by MPE/V (STDLIST=) or MPE/iX (ECHO=,
MSG=, and SPEED=) on the MPE :SET command are also permitted in MPEX.  The
behavior of these options is exactly the same in MPEX as it is in MPE/V and/or
MPE/iX.

The %SET STDLIST= option (used to indicate what is to be done with the running
job's output spool file) is identical to MPE/V's (and MPE/iX's) -- look in the
MPE Commands Manual for more information.

%SET MSG=ON is the same as MPE/V's (and MPE/iX's) :SETMSG ON; %SET MSG=OFF is
the same as MPE/V's (and MPE/iX's) :SETMSG OFF.

%SET SPEED=x is the same as MPE/V's :SPEED x,x command except that the %SET
SPEED= parameter is in bits per seconds -- the :SPEED parameter is in
characters per second.  Thus, instead of saying :SPEED 960,960, you'd say %SET
SPEED=9600 -- the %SET SPEED= parameter should always be 10 times more than the
:SPEED parameter.

%SET ECHO=ON and %SET ECHO=OFF, true to their names, turn echo on and off.

Syntax:   %SETLVAR varname expression

Examples: %SETLVAR COUNTER 1
          %SETLVAR ANSWER UPS(ANSWER[0:1])
          %SETLVAR JULIANDAY TODAY-DATEBUILD(HPYEAR,1,1)+1

The %SETLVAR command evaluates an expression and assigns its value to an MPEX
local variable.  Please see "Local Variables" in the MPEX Variables chapter of
this manual for more details.


_SETVAR_928
%SETVAR

Syntax:   %SETVAR varname expression

Examples: %SETVAR NUMFILES NUMFILES+1
          %SETVAR FRECSIZE -VEFINFO(FNAME+".DEV.AP").RECSIZE
          %SETVAR NUMBERISVALID BETWEEN(NUMINPUT,-5,15+NUMWIDGETS)
          %SETVAR FOURTHREC VEFREADDIR("DATAFILE,OLD",3)
          %SETVAR C SQRT((A)+(B))
          %SETVAR LASTDAYOFLASTMONTH DATEBUILD(HPYEAR,HPMONTH,1)-1
          %SETVAR LASTFRIDAY TODAY-DATEDAYOFWEEK(TODAY-6)
          %SETVAR NEXTFRIDAY TODAY+7-((HPDAY+1) MOD 7)
          %SETVAR JULIANDAY TODAY-DATEBUILD(HPYEAR,1,1)+1

The %SETVAR command evaluates an expression and assigns its value to an MPEX
variable (see the MPEX Variables chapter).  This variable can later be
substituted into MPEX commands, and used in %IFs, %WHILEs, %CALCs, and other
%SETVARs.

If the variable "varname" exists, its old value will be overwritten with the
new; if it doesn't exist, it will be created.

The expression can be any VESOFT expression, not just an ordinary MPE
expression.  The syntax of VESOFT expressions is described fully in the
Appendix.

VESOFT expressions support real numbers, dates, and times as well as integers,
booleans, and strings.  Unfortunately, MPEX variables can only be integers,
booleans, and strings (because of the restrictions imposed by MPE/iX with which
we must be compatible).  If the expression returns a real number, a date, or a
time, that value will be nicely formatted into a string, and the variable
"varname" will be a string variable.


_SHOW_929
%SHOW

Syntax:   %SHOW

Examples: %SHOW
          SET CAPABILITY,RELEASE,SM
          SET DEFAULT,PURGE,?
          SET DATE,MDY

Shows the values of all the

   * %SET CAPABILITY (capability restrictions on MPEX commands),

   * %SET DEFAULT (default modes of execution for MPEX commands), and

   * %SET DATE (input date format, MDY vs.  DMY vs.  YMD)

options that have been set.

Syntax:   %SHOWALARM
          [;ALL]
          [;FROM=mpeuserset]

Examples: %SHOWALARM
          %SHOWALARM;ALL
          %SHOWALARM;FROM=@.DEV

%SHOWALARM shows information about the alarms you set via the %ALARM command.
For more information, see the documentation on %ALARM.

Syntax:   %SHOWGOON

Examples: %SHOWGOON

FILENAME  [STATUS]  COMMAND

VEOU53    [done]    PRINT @.SOURCE;SEARCH="SOC-SEC-RATE";NUM
          VEOU73    [active]  ALTFILE @.@.DEV; XLTRIM; KEEPAMDATES
          VEOU94    [active]  COBOL MYPROG.SOURCE,=.PUB

%SHOWGOON displays the status of all of your %GOON processes.  For more
information, please see the %GOON command in this manual.


_SHOWJOB_930
%SHOWJOB


_LISTJOB_931
%LISTJOB

Syntax:   %SHOWJOB [mpe showjob parameters]
                   [;JOB=@A]
                   [;NOSEC]

Examples: %SHOWJOB JOB=@A
          %SHOWJOB SCHED;NOSEC
          %SHOWJOB JOB=@.SYS;*LP

%SHOWJOB

JOBNUM  STATE IPRI JIN  JLIST    INTRODUCED  JOB NAME

#S2     EXEC        20  20       WED  7:41A  CHUCK,MANAGER.SYS
#J3     EXEC        10R LP       WED  7:43A  BACKG,MANAGER.VESOFT
#S3     EXEC         2  2        WED  8:05A  RON,MANAGER.TECH
#S4     EXEC QUIET   3  3        WED  8:05A  VLADIMIR,MANAGER.VESOFTD
#S6     EXEC         5  5        WED  8:10A  SCOTT,MANAGER.TECH
#S9     EXEC         9  9        WED  9:16A  TOM,MANAGER.VESOFTD

7 JOBS:
    0 INTRO
    0 WAIT; INCL 0 DEFERRED
    7 EXEC; INCL 6 SESSIONS
    0 SUSP
JOBFENCE= 6; JLIMIT= 2; SLIMIT= 40

JOBNUM  STATE R SCHED-CONDITION  SCHEDULED-INTRO   JOB NAME

#A1     SCHED +                   SMTWRFA  0:10    GETDFREE,MANAGER.TECH
#A2     SCHED +                   -MTWRF-  0:15    DAILY,MGR.XPRESS
#A3     SCHED +                   S-----A  0:35    DISCLEAN,MANAGER.SYS
#A4     SCHED +                   -MTWRF-  1:30    BACKUP,MANAGER.SYS
#A5     SCHED + WHENEVER BETWEEN(HPDAY,2,6) AND...  REMOTE,USER.XPRESS
#A6     SCHED + WHENEVER (HPDATE=1)                REPORT,MANAGER.SYS
#A7     SCHED                FRI  9/16/94 10:00    TESTSCHD,MANAGER.SYS

7 STREAMX SCHEDULED JOBS.

The MPE :SHOWJOB command has been enhanced to display STREAMX scheduling
information as well as MPE :SHOWJOB information.  When appropriate, STREAMX
scheduling information is automatically displayed after the status section of
the MPE :SHOWJOB command.  In addition, we have created an new %SHOWJOB userset
of @A to represent all STREAMX scheduled jobs.

The SCHED-CONDITION/SCHEDULED-INTRO columns display different information
depending upon whether or not the job repeats on specific days, is scheduled to
submit on a particular day and time, or if the job should be launched when a
particular condition occurs.  Repeating jobs are indicated by a "+" character
after the word "SCHED".  For jobs that are scheduled for a particular day &
time, that information is displayed much the same as MPE scheduled jobs.  For
conditional jobs, as much of the condition that can be displayed on one line
will be printed, followed by "..." if the conditional expression is longer.

This is essentially the same format as the %SHOWJOB command, and shows the same
information as the %SEC SHOWSCHED command.  %SEC SHOWSCHED, however, will
display the entire condition under which a job will be submitted.

Since the default is to display both jobs and sessions, simply typing %SHOWJOB
alone will display MPE jobs and sessions, MPE scheduled jobs, the MPE status
block, and STREAMX scheduled jobs in that order.  To display only STREAMX
scheduling information, type %SHOWJOB JOB=@A.  To suppress STREAMX scheduling
information, include ;NOSEC as part of the command.

Syntax:   %SHOWLVAR [varset] [ ,...  ]

Examples: %SHOWLVAR COUNTER
          %SHOWLVAR J, K, L
          %SHOWLVAR K#, FOO@

The %SHOWLVAR command shows local variables.  Please see "Local Variables" in
the MPEX Variables chapter of this manual for more details.


_SHOWME_932
%SHOWME

Syntax:   %SHOWME [;DETAIL]

Examples: %SHOWME;DETAIL

The MPE :SHOWME command has been enhanced to display additional information
when you have changed from your original LOGON to a new LOGON using the
%CHLOGON or %CHGROUP commands.  The example below shows the additional
information that is displayed when the optional ;DETAIL parameter is used.

%chlogon tom,vanilla.user,tom
Welcome! You are now signed on.
%showme;detail
CURRENT LOGON: TOM,VANILLA.USER,TOM
        CAPS: ND,SF,BA,IA
ORIGINAL LOGON: TOM,MANAGER.SYS,PUB

USER: #S135,VANILLA.USER,TOM       (IN PROGRAM)
RELEASE: B.40.00   MPE/iX HP31900 B.30.45   USER VERSION: B.40.00
CURRENT: THU, JUN 17, 1993, 11:35 AM
LOGON:   THU, JUN 17, 1993,  9:02 AM
CPU SECONDS: 27         CONNECT MINUTES: 153
$STDIN LDEV: 11         $STDLIST LDEV: 11


_SHOWOUT_933
%SHOWOUT

Syntax:   %SHOWOUT spoolfileset[;listfile]

Examples: %SHOWOUT $STDLIST.@.@
          %SHOWOUT @.@.PROD(SPOOL.JSNAME="COMP010")
          %SHOWOUT @.@.@(SPOOL.OUTPRI>=5)

The %SHOWOUT command shows information on output spool files.  In this, it's
similar in purpose to MPE's :SHOWOUT and SPOOK5's >SHOW, but is appreciably
more powerful:

   * It lets you select which spool files you want to list; for instance, to
     find the PROD account spool files belonging to the job with job name
     COMP010, you can just say:


Spool_files__selecting_by_creating_job_session_name_934
Spool files: selecting by creating job/session name

        %SHOWOUT @.@.PROD(SPOOL.JSNAME="COMP010")

     Similarly, to find the spool files of all jobs that terminated with an
     error, you may enter:


Spool_files__selecting_spool_files_of_aborted_jobs_935
Spool files: selecting spool files of aborted jobs

        %SHOWOUT @.@.@(SPOOL.JOBABORTED)

   * Its output has rather more interesting information:

   SPFile# Filename Pri  JOB#:jobname,user.acct,group   Ready Date
   #O869   LP        7  #J493:SORTCITY,MGR.SALES,PUB    WED 11:45AM
   #O733   CONTRACT  6  #J427:CONT,TEST.AP,DATA         TUE 11:23AM
   #O1181  $STDLIST  3  #J620:COMP010,JACK.AP,DEV       FRI 9:24AM
   #O1198  $STDLIST  3  #J632:COMP030,PETE.AP,DEV       FRI 9:55AM ERR!

The output includes:

    - The full logon of the job involved (including the session name).

    - The spool file's output priority.

    - The date that the spool file was made ready.  If the date is within the
      past week, it's shown as a day of week (e.g.  WED); if it's earlier, it's
      shown as the day of month and month name (e.g.  17APR).  If the spool
      file has not yet been made ready, "(OPENED)" is shown in this column.

    - The string "ERR!" if the job is marked as having terminated abnormally
      (i.e.  because a command that was not preceded by a !CONTINUE got a fatal
      error) -- the SPOOL.JOBABORTED selection condition lets you select by
      this flag.

We think that the %SHOWOUT command is a good replacement for MPE :SHOWOUT and
for SPOOK5 >SHOW.  Just the fact that it shows the job name can make it
worthwhile -- no more >TEXTing spool files one by one and >LISTing their :JOB
cards to find the one you want.

MPE/iX Native Mode Spooler Note


MPE_V_and_MPE_iX_differences__NM_spooler__SHOWOUT_936
MPE/V and MPE/iX differences: NM spooler %SHOWOUT

The Native Mode Spooler on MPE/iX does not retain the spoolfile's group name.
If you specify a group name in %SHOWOUT on MPE/iX, it will be effectively
ignored.  For example,

%SHOWOUT $STDLIST.PUB.PROD...

is the same as

%SHOWOUT $STDLIST.@.PROD...


_SHOWOUTJ_937
%SHOWOUTJ

Syntax:   %SHOWOUTJ [jobsessionname][,user.account]

Examples: %SHOWOUTJ DAILY,@.VESOFT
          %SHOWOUTJ XXX         is the same as  %SHOWOUTJ XXX,@.@
          %SHOWOUTJ ,USER.ACCT  is the same as  %SHOWOUTJ @,USER.ACCT

%SHOWOUTJ is simply a very useful special case of %SHOWOUT.  It shows you all
the spool files belonging to jobs/sessions with the given job/session name,
user, and account.  For example, to see all the spool files belonging to
jobs/sessions named DAILY that logged on as any user in the VESOFT account:

   %SHOWOUTJ DAILY,@.VESOFT

SPFile# Filename Pri  JOB#:jobname,user.acct,group   Ready Date

   #O923   LP        7  #J493:DAILY,MANAGER.VESOFT,PUB   TUE 12:23AM
   #O755   $STDLIST  1  #J493:DAILY,MANAGER.VESOFT,PUB   TUE 12:23AM
   #O1150  $STDLIST  1  #J505:DAILY,TEST.VESOFT,PUB     (OPENED)

This command is quite useful if you frequently have many jobs that log on with
the same user ID but with different job names.  Trying to find a particular
job's spool file with SPOOK5 can be very tough, since SPOOK5's >SHOW only shows
you the user and account names, not the job/session name.

As we mentioned above, this command is just a special case of the much more
powerful %SHOWOUT command.  Saying

   %SHOWOUTJ X@,Y@.Z@

is the same as saying

   %SHOWOUT @.@.Z@(SPOOL.JSNAME MATCHES "X@" and &
                   SPOOL.USER MATCHES "Y@")

Syntax:   %SHOWPAUSED

Examples: %SHOWPAUSED

%SHOWPAUSED shows information about jobs that were suspended via the %PAUSEJOB
command.  For more information, see the documentation on %PAUSEJOB.


_SHOWPROC_938
%SHOWPROC

Syntax:   %SHOWPROC [[PIN=][#P]pin | [PIN=](pin [ ,...  ])]
                    [[JOB=]userset | JOB=(jobID [ ,...  ])]
          [;FORMAT=[SUMMARY|FILES]]
          [;FILES=fileset]
          [;[NO]TREE]
          [;USER|ANYUSER]
          [;SYSTEM]
          [;C[HANGE]]
          [;[NO]TRUNC]                                     (NEW)

Examples: %SHOWPROC #J232
          %SHOWPROC (190,56,110,108)        (* list of pins *)
          %SHOWPROC JOB=(#J132, #J134)      (* list of jobs *)
          %SHOWPROC #J232; FORMAT=FILES     (* info on open files *)
          %SHOWPROC BATCH; FILES=@.DB.PROD(ISPRIV)
          %SHOWPROC LDEV=MODEM
          %SHOWPROC LDEV=MODEM;CHANGE

MPEX's %SHOWPROC command is an improved version of the MPE/iX :SHOWPROC
command; it provides the following enhancements:

   * it displays the job/session number, job/session name, user name, account
     name, and group name before the first PIN of each job/session;

   * it lets you list just those processes which have used CPU since the last
     %SHOWPROC command you entered;

   * it will show you information about any (or particular) files that the
     processes you're displaying have open (perm and temp files);

   * it shows you the command line or ;INFO= string of each process (which may
     be truncated using the ;TRUNC keyword if the process nesting is too deep);

   * it works on MPE/V!

%SHOWPROC entered without any parameters will show you all of the processes in
your current job/session:

   %SHOWPROC
   QPRI  CPUTIME   STATE  JOBNUM  PIN  (PROGRAM) STEP
                         #s187, eugene,manager.tech,eugene (ldev 20)
   C152  0:02.425  WAIT   S187    17   :RUN MPEX.PUB.VESOFT
   C152  0:00.304  WAIT   S187      105  (MPEX.PUB.VESOFT)
   C158  0:11.023  READY  S187        88   (MAIN.PUB.VESOFT)
   C152  0:00.321  MSG    S187          32   (WAKEUP.PUB.VESOFT)

You may specify a PIN or list of PINs to show particular processes, or a
job/session ID, a list of job/session IDs, or a VESOFT userset to show all
processes for a particular job or or set of jobs (in this discussion, job means
job or session).  If you don't specify any job, userset, or PIN, you will be
shown information about your current job/session.


USER_939
USER


ANYUSER_940
ANYUSER
"Normal" users (users without SM or OP capability) will only be allowed to view
information on processes logged on with their same user.account.  SM/OP users
by default will be shown information about any jobs/sessions that match the
userset they specify.  They can limit the output to jobs/sessions matching
their user.account by saying ";USER".  (This is mostly for compatibility with
MPE/iX.)

If you have OP capability, you can show any user process(es), but not system
processes.  If you have SM capability, you can show any user or system
process(es).


TREE_941
TREE


NOTREE_942
NOTREE
If you specify a PIN (or list of PINs), %SHOWPROC defaults to ;NOTREE -- only
show the process(es) whose PIN(s) were specified, not their sons.

If you specify a jobID (or list of jobIDs) or VESOFT userset, the default is
;TREE -- all processes in each qualifying job are shown.


CHANGE_943
CHANGE
The ;CHANGE keyword allows you to show just those processes that have used CPU
time since the last execution of %SHOWPROC! (You must do at least one
%SHOWPROC, without ;CHANGE, that includes the process(es) you are interested in
before using ;CHANGE.) For example, if you do a

   %SHOWPROC OPERATOR.SYS

and then later do a

   %SHOWPROC OPERATOR.SYS; CHANGE

the second %SHOWPROC will only show those processes that have used CPU time
since the execution of the first %SHOWPROC; the CPUTIME column will show the
CPU used since the last %SHOWPROC rather than (as it normally does) the total
CPU used by each process.


TRUNC_944
TRUNC


VESOFTDEFAULTSHOWPROC_945
VESOFTDEFAULTSHOWPROC
The output of the %SHOWPROC command includes the command line or ;INFO= string
passed to each program.  When a process tree has several nested processes or
the ;INFO= strings are quite long, the ;INFO= that we display will wrap around
to the next line of your screen.  While this isn't serious, it can make reading
the output of this command difficult, so we have created a ;TRUNC keyword that
will truncate the output at 80 characters.  You may want to set this as a
default using the VESOFTDEFAULTSHOWPROC variable.  If you have set this
variable, you can use ;NOTRUNC to override the VESOFTDEFAULTSHOWPROC setting.
Truncated lines are identified with a '$' character in the last position.

SHOWING WHICH FILES A PROCESS HAS OPEN (;FORMAT=FILES)


FORMAT_FILES_946
FORMAT=FILES
MPEX's %LISTF ,ACCESS (documented elsewhere in this manual) has long been one
of our most popular commands.  It gives you information about everyone who is
accessing a particular file (or fileset).  But, sometimes what you want is just
the opposite: you want to know which files a particular user (or userset) is
accessing.  The ;FORMAT=FILES option gives you this information!

For example, if you want to see what the job LONGTIME,BATCH.PROD is doing at
the moment, you could type:

   %SHOWPROC LONGTIME,BATCH.PROD; FORMAT=FILES

This will show you, for every file the job currently has open (in addition to
the normal process information %SHOWPROC displays):

   * the file number, full name, and file code, and record size;

   * the type of access the file is opened for (Read, Write, Append, execute,
     lock);

   * the current EOF;

   * the current record number;

   * the number of disc I/Os this process has performed against this file.

%SHOWPROC shows this information for both temporary and permanent files!


FILES__947
FILES=
The ;FORMAT=FILES keyword shows all of the files that every process in the
process tree has open.  Often, this provides too much information -- you may be
interested in only one particular file or fileset instead of every file.  Even
though %LISTF ,ACCESS shows the information for a file or fileset, it also
shows you every user accessing the file, which again can be "too much"
information (besides, %SHOWPROC shows more information about how this process
is accessing the file than %LISTF does).  To limit the output of the %SHOWPROC
command to only those files that are in a given fileset, use the keyword
;FILES=fileset instead (in fact, ;FORMAT=FILES is equivalent to ;FILES=@.@.@).

Syntax:   %SHOWSAVED;FILE=savefile

Examples: %SHOWSAVED;FILE=SAVEDJBS

%SHOWSAVED shows information about jobs that were saved via the %SAVEJOB
command.  For more information, see the documentation on %SAVEJOB.


_SHOWTREE_948
%SHOWTREE

Syntax:   %SHOWTREE

%SHOWTREE shows the entire process tree of your session, e.g.

   %SHOWTREE
   24    C.I.
     19    MPEX.PUB.VESOFT
       28    MAIN.PUB.VESOFT (active) [you are here]
         75    WAKEUP.PUB.VESOFT (active)
         53    EDITOR.PUB.VESOFT
           66    MPEX.PUB.VESOFT
         17    SPOOK5.PUB.SYS

Note: Since MPEX is a CM shell program that runs the MAIN program (which will
      be NM for MPE/iX systems and CM for MPE/V systems), the "you are here"
      marker will appear on the MAIN program and not the MPEX program.  This is
      normal.

The "[you are here]" marks the MPEX process; the indentation indicates who is
whose son (PINs 17, 75, and 53 are the sons of MAIN [PIN 28] -- PIN 66 is the
son of PIN 53).

Once you know that, say, SPOOK5.PUB.SYS is PIN 17, you can type

   %RUN 17

to re-activate it, or

   %KILL 17

to kill it.  Of course, you could have always said

   %SPOOK5

or

   %KILL SPOOK5.PUB.SYS

(referred to the son process by its program name) -- but referring to it by PIN
can also be useful sometimes (to save typing or to resolve ambiguities if you
have two son processes with the same name).


_SHOWVAR_949
%SHOWVAR

Syntax:   %SHOWVAR [varset] [ ,...  ]

Examples: %SHOWVAR        << shows all your own variables >>
          %SHOWVAR @      << shows all variables, including >>
                          << system-defined variables >>
          %SHOWVAR X, TEMPV@

The %SHOWVAR command shows the values of the specified MPEX variables (see the
MPEX Variables chapter for more information).

Typing

   %SHOWVAR

will show all of the modifiable variables (mostly the ones that you've set
yourself and the ones that MPEX uses for control purposes).  On the other hand,

   %SHOWVAR @

will show all the variables, including the predefined non-modifiable ones, like
HPACCOUNT, HPUSER, etc.; for instance:

   AP = PURGERBM SEGMENT,EXP'
   MPEXPREFIX = !
   MPEXFILESET = MY@
   VESOFTPAGESIZE = 60
   HPACCOUNT = VESOFT
   HPCMDNUM = 6
   HPCPUNAME = SERIES MICRO/XE
   HPDATE = 30
   HPDATEF = SAT, JAN 30, 1991
   ...

To see the value of a specific variable or set of variables, you can say

   %SHOWVAR AP
   AP = PURGERBM SEGMENT,EXP'

or

   %SHOWVAR HPDATE@,A?
   HPDATE = 30
   HPDATEF = SAT, JAN 30, 1991
   AP = PURGERBM SEGMENT,EXP'

As you see, you can use wildcards (@, ?, and #) to select those variables you
want.


_SPOONFEED_950
%SPOONFEED


cmd_syntax__951
cmd syntax


_cmd_syntax__952
>cmd syntax

Syntax:   %SPOONFEED progname, cmd
          %>cmd     (to execute cmd as a SPOOK5 command)
          %'cmd     (to execute cmd as a QUERY command)

Examples: %>TEXT 1234
          %>LIST 10/20
          %'FIND CUST-NO="X985"
          %'REPL CUST-NAME="JOHN SMITH & CO."; END

Many programs (EDITOR, QUERY, etc.) allow you to execute some MPE commands from
within them simply by prefixing the command with a ":".  Similarly, all MPEX
HOOKed utilities let you execute MPEX commands from within them by prefixing
the command with a "%".

Imagine that you could similarly execute SPOOK5 or QUERY commands, or commands
of any other utilities -- instead of running QUERY, executing the command,
exiting QUERY, and then re-running it the next time you need to do a QUERY
command, you could just say

   %'FIND STATE=CA,TX,WA

All that you have to do to execute a QUERY command is to prefix it with a "'"
character.  Similarly, to execute a SPOOK5 command, you can just say

   %>TEXT 1234

-- prefix the SPOOK5 command with a ">".  If you need to do several commands,
no problem -- SPOOK5 is kept as a son process and is passed each command as you
type it; you might say

   %>TEXT 1234
   %>LIST 1/20

You might even put all these ">"-prefixed commands in a command file; the same
command file can mix MPEX commands, QUERY commands, SPOOK5 commands, and so on!

Needless to say, all this is available to you if use MPEX from an MPEX HOOKed
program.  Thus, if you "live in" EDITOR and use the MPEX HOOK to compile, :RUN,
etc., you will also be able to say:

   /%SHOWOUT        << use MPEX's %SHOWOUT command>>
   /%>TEXT 1234     << text spool file #1234 into SPOOK5 >>
   /%>LIST 10/20    << execute SPOOK5's >LIST command >>

Two characters -- the "%" for MPEX and the ">" for SPOOK5 -- are all you need
to do to execute a SPOOK5 command from within EDITOR!

We call this process "spoon-feeding" -- we keep SPOOK5, QUERY, or whatever else
as a son process and pass it one command at a time.  As soon as the program
involved executes that command and prompts for more input, control is returned
to MPEX (or whatever MPEX HOOKed program you're using MPEX from).

This actually works regardless of what sort of input the "spoon-fed" program
prompts you for (a command or some other kind of input).  Thus, a typical
"spoon-fed QUERY" conversation might look like this:

   %'BASE=MYDB
   HP32216D.00.08 QUERY/3000

   PASSWORD =                   << QUERY prompt >>
   %'MYPASS
   MODE =                       << QUERY prompt >>
   %'5
   >                            << QUERY prompt >>
   %'FIND CUST-NO="X987"
   ...

Every time QUERY prompts you for input, control is returned to MPEX, and QUERY
remains suspended until you enter the next command that starts with "'" -- this
command will then re-activate QUERY and send it the data that you want.

Note that this sort of approach might take some getting used to.  For instance,
many programs (like QUERY and EDITOR) will output their own prompt to you
before re-activating MPEX; thus, you'll see not just MPEX's "%" prompt but also
the program's prompt before it.  Also, in the example above, QUERY turned off
echo when prompting for the password; echo will remain off for MPEX until you
either do a "%SET ECHO=ON" command or send the password to QUERY (which will
cause QUERY to turn echo back on).  However, all in all, we think that this can
be a very powerful time-saving feature.

Another way to look at spoon-feeding is that it doesn't "mode you in"; instead
of having "EDITOR mode", "MPE mode", "QUERY mode", "SPOOK5 mode", etc., you can
readily execute any kind of command you want from one environment (typically
either MPEX or your favorite MPEX HOOKed text editor).

HOW TO USE SPOONFEEDing

All of the above has been an introduction to the benefits of what we believe to
be a rather novel feature.  How exactly can you get it to work for you?


SPOONFEEDing_953
SPOONFEEDing
Well, technically speaking, the fundamental spoon-feeding command is

     %SPOONFEED progname, cmd

For instance, to execute a QUERY command, you'd say

     %SPOONFEED QUERY, FIND CUST-NO="X987"

This will execute QUERY.PUB.VESOFT (this program must be an MPEX HOOKed program
in PUB.VESOFT -- QUERY is MPEX HOOKed automatically when you install our
software) and pass to it the FIND command.

Of course, if you had to type "SPOONFEED QUERY, " before every QUERY command
you wanted to execute, it wouldn't be much better than having to run QUERY and
execute the command directly from QUERY.  Fortunately, we let you define the
meaning of any special character (except for the reserved characters "%", "!",
"?", "$", ":", and "," [comma]) used as the first character of an MPEX command.
In the default MPEXMGR.PUB.VESOFT file, we say:


MPEXPREFIXDEFnn_954
MPEXPREFIXDEFnn

     %:SETVAR MPEXPREFIXDEF39 "SPOONFEED QUERY,"

This means: "Set the DEFinition of PREFIX character 39 (which is the ASCII code
for a single quote) to be 'SPOONFEED QUERY,'".  (If you haven't memorized the
ASCII table yet, you could have said %CALC ORD("'") to find out the ASCII
code.) Whenever MPEX sees a command that starts with a "'", it will replace the
quote by "SPOONFEED QUERY,", which will then cause the command to be executed
as a QUERY command.

The default MPEXMGR.PUB.VESOFT file also says:

   %:SETVAR MPEXPREFIXDEF62 "SPOONFEED SPOOK5,"

This defines ">" as the prefix character for commands to be executed from
SPOOK5.PUB.VESOFT.  In case you're interested, ">" was chosen because it is the
SPOOK5 prompt and should thus be easy to remember; "'" was chosen for QUERY
because we hoped that "quote" and "query" were close enough to help you
remember the correspondence.  (">"  was already taken by SPOOK5 and "?" already
had another meaning in MPEX.)

Needless to say, you can in this way define your own spoon-fed programs.  If,
for instance, you frequently use KSAMUTIL, you can say

     %HOOK KSAMUTIL.PUB.SYS

to make an MPEX HOOKed copy of it in PUB.VESOFT, and then add a line to
MPEXMGR.PUB.VESOFT that says

     %:SETVAR MPEXPREFIXDEF94 "SPOONFEED KSAMUTIL,"

This will define "^" (ASCII 94) as the prefix character for KSAMUTIL command --
of course, you can use some other character if you prefer, or you might even
set up a command file called "K" that says

   ANYPARM CMD
   SPOONFEED KSAMUTIL,!CMD

and then you'll be able to execute KSAMUTIL commands from MPEX simply by saying

   %K BUILD MYFILE;KEYFILE=MYFILEK;KEY=...

(There's nothing that says that you have to use special characters to identify
spoon-feeding commands.)

AN IMPORTANT WARNING

As we mentioned before, if you use spoon-feeding you might have to get used to
a few new considerations.  One of the most important ones has to do with the
fact that the spoon-fed process remains alive even when you're not in it.  In a
way, this is obvious, since this is the whole point of spoon-feeding; however,
this also means that any files that the process has opened remain opened and
any resources that it has locked remain locked.

A classic example of this is when you're spoon-feeding SPOOK5; if you say

   %>TEXT 1234

then #O1234 will be locked by the SPOOK5 process; you might easily forget that
you have a spoon-fed SPOOK5 son process, and not realize that the spool file is
now locked, and thus can't be purged or printed.  To unlock it, you'd have to
say

     %>QUIT

to terminate SPOOK5 (which will require SPOOK5 to be recreated the next time
you do a "%>" command).

A similar problem can happen if you're spoon-feeding QUERY and do a %'FIND
command without previously doing an %'ASSIGN LOCKOPTION=OFF.  The FIND command
will lock the entries it finds, which is not bad by itself; however, if you
then run your own program from within MPEX and it tries to lock something, the
program will either get an error indicating that it tried to lock something
while the session already holds a lock.

Furthermore, if your program was :PREPed with ;CAP=MR (which explicitly turns
off this lock-time checking), you can cause a mini-deadlock -- your program
will be waiting for a lock that is held by QUERY, while QUERY will be waiting
for reactivation by MPEX, which in turn is waiting to be reactivated by your
program.  You would then have to do a [BREAK] and :ABORT to get out of this.

GETTING INFORMATION ON WHICH PROGRAMS YOU'RE SPOONFEEDing

Here are a few ways in which you can see the state of the programs you are
currently spoon-feeding:

   * A %SHOWTREE will show you all of your son processes, including the ones
     you're spoon-feeding.


MPEXSONEXECPIN_955
MPEXSONEXECPIN
   * The PIN (Process Identification Number) of a spoon-fed process is kept in
     the JCW MPEXSONEXECPINprogname, where the "progname" is fully qualified.
     Since the "." character isn't legal in a variable name, the "."'s are
     changed to the letter "Z".  For instance, the PIN of a spoon-fed QUERY
     would be in MPEXSONEXECPINQUERYZPUBZSYS.

   * If you've forgotten where you are in a particular spoon-fed process,
     remember that all spoon-fed processes are running MPEX HOOKed programs --
     you can use the MPEX HOOK LISTREDO facility to see which commands you've
     executed through this spoon-fed program.  For example, entering
     "':LISTREDO" (or ',,) will show you the last 20 commands you've spoon-fed
     to QUERY.


_SPOONINIT_956
%SPOONINIT

Syntax:   %SPOONINIT programfile ;MPEX %run parm [ ;...  ]

Examples: %SPOONINIT QEDIT;PARM=7

Occasionally, you may need to supply a "runtime" parameter to the program being
spoonfed (such as a ;PARM= value for QEDIT or an ;INFO= string).  %SPOONINIT
allows you to do this; however, it must be used as the FIRST "spoonfeed" type
command for the program and does not allow you to actually specify a command to
be "spoonfed".

Although ;INFO= and ;PARM= are most likely to be the only parameters you would
need to specify, the following parameters may be used as well (of course, you
should not use any parameters from this list if they cause your program to
abort outside of MPEX):

   ;DL
   ;INFO
   ;LMAP
   ;MAXDATA
   ;NMHEAP  (NM)
   ;NMSTACK (NM)
   ;PARM
   ;PRI
   ;STACK
   ;STDLIST

The following %:RUN parameters should be avoided as they will interfere with
our processing of the spoonfeed command:

   ;DEBUG (used for debugging, we cannot supply input in this case)
   ;GOON
   ;INMSG
   ;INPUT
   ;KILL
   ;NEW (we supply this in our command)
   ;NOACTIVATE (we supply this in our command)
   ;NOPRIV
   ;STDIN (SPOONFEED provides the STDIN input)
   ;UNSAT (used for debugging)
   ;XL= (NM) or ;LIB= (CM) (we supply this in our command)


_SUBMIT_957
%SUBMIT


Batch_execution_of_MPEX_commands___SUBMIT_958
Batch execution of MPEX commands: %SUBMIT

Syntax:   %SUBMIT "[joblogon] [;jobparms]", mpexcommand

Examples: %SUBMIT ";OUTCLASS=,1;INPRI=2;PRI=ES", &
                  COBOL AP@.SOURCE, AP@.PUB
          %SUBMIT "MANAGER.SYS", PURGE LOG####.PUB.SYS
          %SUBMIT "MGR.PROD;OUTCLASS=SLOWLP,3", RUN MYPROG;PARM=1234

The %SUBMIT command makes MPEX submit a job that will execute the given MPEX
command.

   * You may (optionally) indicate that the job is to be submitted under
     somebody else's user ID or with some special job parameters.

   * You may execute either an MPEX command or a normal MPE command (RUN,
     STORE, a UDC, etc.); if the MPE command has the same name as an MPEX
     command (like FCOPY), precede it with  a ":".

   * All the file equations that are in effect in your session, and the current
     value of your HPPATH variable, will automatically be copied to the created
     job.

   * You may indicate who MPEX should notify of the job's completion by setting
     the MPEXTELLBACK variable.

   * You may indicate how MPEX should inform you of the job's completion by
     setting the MPEXTELLBACKCMD variable.

(See the %SCHEDULE chapter and "Batch Execution ('$' Prefix)" in the MPEX
Commands chapter for more information.)

To execute an MPEX command in a job stream, you can simply say

   %$COBOL AP@.SOURCE, AP@.PUB

The "$" prefix tells MPEX to perform the command offline -- MPEX will
automatically generate a job stream that executes the above command.

It'll also copy all the :FILE-equations (such as :FILE COPYLIB=...) that you
may have in your session into the job, so that the job environment is as close
as possible to your session environment.

The %SUBMIT command simply extends this capability to allow you to specify a
different logon ID and :JOB card parameters for the job stream.  Saying

   %$COBOL AP@.SOURCE, AP@.PUB

will execute "COBOL AP@.SOURCE, AP@.PUB"

   * under your own logon id

   * with the job parameters ";OUTCLASS=,1".

What if you want to submit it at input priority 2 with CPU priority ES? Just
say:

   %SUBMIT ";OUTCLASS=,1;INPRI=2;PRI=ES", COBOL AP@.SOURCE, AP@.PUB

If you say

   %SUBMIT "MGR.PROD;OUTCLASS=SLOWLP,3", COBOL AP@.SOURCE, AP@.PUB

then it'll not only use the given job card parameters but also the given logon
ID (MGR.PROD).  Saying just

   %SUBMIT "MANAGER.SYS", PURGE LOG####.PUB.SYS

will only change the logon ID (MANAGER.SYS) while keeping the default job card
parameters (;OUTCLASS=,1).

Of course, if you try to submit something under somebody else's logon ID, MPEX
will prompt you for the passwords (unless you have SM capability, or AM
capability in your own account).

If you always want to submit your jobs with a particular set of !JOB card
parameters (other than the default ";OUTCLASS=,1"), you might want to add a
%SETVAR MPEXDEFAULTJOBPARMS to your MPEXMGR, MPEXMGR.PUB, or MPEXMGR.PUB.VESOFT
file to set the special MPEXDEFAULTJOBPARMS variable to your default !JOB card
parameters.  For example, you might say:

        %SETVAR MPEXDEFAULTJOBPARMS "OUTCLASS=,2;PRI=ES"

If you do this, all the jobs you submit with the "$command" syntax (or with the
%SUBMIT command in which you only specify a different logon ID, not a different
set of !JOB card parameters) will be submitted with OUTCLASS=,2 and PRI=ES.


_SYNTAX_959
%SYNTAX

Syntax:   %SYNTAX [mpexcommand]

Examples: %SYNTAX
          %SYNTAX ALTFILE
          %SYNTAX PRINT

MPEX has a lot of new commands, and adds many features to existing MPE
commands.  To help you take full advantage of the increased power MPEX gives
you over your HP3000, we provide a very easy-to-use conceptual on-line help
facility (see the documentation on the %HELP command for details).

Sometimes, however, all you want is a quick reminder of the syntax of a
particular command.  For this purpose, we provide the %SYNTAX command.

Typing

     %SYNTAX ALTFILE

for example, will take you directly to the syntax diagram for MPEX's ALTFILE
command.  Typing

     %HELP ALTFILE

would give you a list of topics related to the %ALTFILE command, and ask you
which one you would like help on.


_TELL_960
%TELL

Syntax:   %TELL userset [[;]text]

Examples: %TELL EUGENE,@.@&ONLINE Lunch time!
          %TELL @,MANAGER.@+@,MGR.@ System will be down tonight...
          %TELL LDEV=113 Is anyone there?
          %TELL LDEV=DIALIN Please hang up soon, or be aborted.

The %TELL command is an enhanced version of MPE's :TELL command.  It allows you
to specify which sessions to :TELL to using VESOFT usersets (see the usersets
section of the SECURITY User Manual).


_TRAPERROR_961
%TRAPERROR


_IFERROR______ENDIFERROR_962
%IFERROR ... %ENDIFERROR


_CLEANUP______ENDCLEANUP_963
%CLEANUP ... %ENDCLEANUP

Syntax:   %TRAPERROR
          %command
           ...
          %command
          %IFERROR|CLEANUP
          %   command
           ...
          %   command
          %ENDIFERROR|ENDCLEANUP

Although MPE lets you do rudimentary error handling with :CONTINUE,
:IF/:ELSE/:ELSEIF/:ENDIF, and the CIERROR JCW, this can prove to be very
cumbersome.  For instance, say that you want to do the commands A, B, C, and D,
but once one of them gets an error, you want to avoid doing the others without
aborting the UDC, command file, or job (perhaps because you want to do some
cleanup at the end).  You'd have to say something like:

   SETJCW CIERROR=0
   CONTINUE
   A
   IF CIERROR=0 THEN
     CONTINUE
     B
     IF CIERROR=0 THEN
       CONTINUE
       C
       IF CIERROR=0 THEN
         CONTINUE
         D
       ENDIF
     ENDIF
   ENDIF
   IF CIERROR<>0 THEN
     TELLOP ERROR IN THE PROCESSING
   ENDIF

MPEX has a  very useful construct that can let you do this much more easily:

  TRAPERROR
  A
  B
  C
  D
  IFERROR
    TELLOP ERROR IN THE PROCESSING
  ENDIFERROR

This syntax tells MPEX to do the commands between the %TRAPERROR and the
%IFERROR until an error occurs, and then, if the error occurs, do the commands
between the %IFERROR and %ENDIFERROR (and then continue with the rest of the
UDC, command file, or job).

As you can see, this is very useful indeed.  For instance, you can make all
your production jobs look like:

   :JOB ...
   :COMMENT   The first thing we do is :RUN CI.PUB.VESOFT, which
   :COMMENT   provides a very good emulation of MPE (plus all the
   :COMMENT   new features.)
   :RUN CI.PUB.VESOFT
   TRAPERROR
   << all the commands you'd normally put into your job >>
   IFERROR
     TELLOP !HPJOBNAME FAILED, ERROR !HPCIERRMSG
   ENDIFERROR
   EXIT
   :EOJ

The jobs will function the same way as before (subject to the relatively few
minor incompatibilities between MPEX and MPE -- test before you commit to
this!), but instead of just blindly aborting, they catch the error and do
whatever cleanup is necessary -- in this case, just a :TELLOP, but it can also
include any necessary :PURGEs and such.

%CLEANUP

Another form of error handling that we've often found useful is doing several
commands, and then, regardless of whether an error occurred or not, doing some
"cleanup" commands, e.g.:

  %BUILD F1
  %BUILD F2
  %TRAPERROR
  %RUN PROG1
  %RUN PROG2
  %...
  %CLEANUP
  %   :PURGE F1
  %   :PURGE F2
  %ENDCLEANUP

Here, the commands between the TRAPERROR and the CLEANUP are executed, and
then, whether or not an error occurred, the commands between the CLEANUP and
ENDCLEANUP are executed.  Then and only then -- after the cleanup commands are
done -- if an error occurred in the TRAPERROR/CLEANUP block, the rest of the
UDC, command file, or job is flushed (subject, of course, to any other
TRAPERROR constructs in which it is itself nested).

Finally, if you want to immediately "jump" to the IFERROR or CLEANUP block you
can use the command:

   %ESCAPE errnum

This sets HPCIERR to errnum, sets CIERROR to the absolute value of errnum, and
skips all statements until the next IFERROR or CLEANUP.

For example:

...
TRAPERROR
IF VEFINFO("FILE1").EOF//VEFINFO("FILE1").FLIMIT > .80 THEN
   ESCAPE 1
ELSEIF VEFINFO("FILE2").EOF//VEFINFO("FILE2").FLIMIT > .80 THEN
   ESCAPE 2
ELSEIF VEFINFO("FILE3").EOF//VEFINFO("FILE3").FLIMIT > .80 THEN
   ESCAPE 3
ENDIF
...
IFERROR
   ECHO ERROR:
   ECHO   FILE!HPCIERR is more than 80% full!!!
   ECHO   Terminating job submission.
   EXIT
ENDIFERROR

For additional information, see the "%ESCAPE" command documented earlier in
this manual.

Syntax:   %UNALIAS aliasname

Examples: %UNALIAS WG
          %UNALIAS SS

%UNALIAS and %ALIAS are closely related commands; please see the documentation
on %ALIAS.


_VEAUDIT_964
%VEAUDIT

Syntax:   %VEAUDIT command

Examples: %VEAUDIT LISTUSER @.@
          %VEAUDIT ALTUSER CAP=SM-MANAGER.SYS;CAP=-SM

The %VEAUDIT prefix allows VEAUDIT users to enter VEAUDIT accounting structure
maintenance commands within MPEX.  Please see "Accounting Structure
Maintenance" in the VEAUDIT User Manual for details.


_VECMDCH_965
%VECMDCH

Syntax:   %VECMDCH fileset [;REMOVE]

Examples: %VECMDCH @.PUB.PROD(ISPROG)

This command allows you to change a program fileset so that it uses STREAMX
instead of STREAM (i.e.  it replaces calls to the COMMAND intrinsic with calls
to the VECMMND intrinsic).

To change a fileset from VECMMND back to COMMAND, use the ";REMOVE" option.

Please see the What if your program does a :STREAM programmatically chapter in
the SECURITY User Manual.


_VEOPENCH_966
%VEOPENCH

Syntax:   %VEOPENCH fileset [;REMOVE]

Examples: %VEOPENCH @.PUB.PROD(ISPROG)

This command allows you to change a program fileset so that it uses VEOPEN
instead of DBOPEN (i.e.  it replaces calls to the DBOPEN intrinsic with calls
to the VEOPEN intrinsic).

To change a fileset from VEOPEN back to DBOPEN, use the ";REMOVE" option.

Please see the Making Program Which Source Code You Don't Have Call VEOPEN
chapter in the SECURITY User Manual.


_WARN_967
%WARN

Syntax:   %WARN userset [[;]text]

Examples: %WARN ONLINE System going down soon; please log off.
          %WARN LDEV=113 Last chance to log off gracefully...
          %WARN LDEV=DIALIN Please hang up soon, or be aborted.

The %WARN command is an enhanced version of MPE's :WARN command.  It allows you
to specify which sessions to :WARN using VESOFT usersets (see the usersets
section of the SECURITY User Manual).

Note: just like in MPE, the WARN command can only be issued from the console,
unless permitted via the ALLOW command.


_WARNF_968
%WARNF

Syntax:   %WARNF userset [[;]text]

Examples: %WARNF ONLINE System going down soon; please log off.
          %WARNF @,MANAGER.@+@,MGR.@ System will be down tonight...
          %WARNF LDEV=113 Last chance to log off gracefully...
          %WARNF LDEV=DIALIN Please hang up soon, or be aborted.
          %WARNF ACCESSING=CUST.DB.PROD Please exit CUSTDB now...

%WARNF is just like %WARN except that it displays the message right over the
function keys (on most new HP terminals), rather than on the actual display
portion of the screen.  This makes it easy for you to send messages to people
without overwriting any of the data that they might have on their screen.  To
erase the message, users can simply press [RETURN].


MPEXWARNFPREFIX_969
MPEXWARNFPREFIX
Unlike the :TELL (or %TELL) command, %WARNF does not include any information
about who sent the message.  To avoid having to manually include your name (or
session number) in every %WARNF message you send, MPEX will prefix the message
with the contents of the variable MPEXWARNFPREFIX (if you %SETVAR it).  For
example, to prefix all %WARNF messages with "From Scott: ", you would do a

   %SETVAR MPEXWARNFPREFIX "From Scott: "

before you do any %WARNFs.  In fact, you may want to include this %SETVAR in
your MPEXMGR file (see "Specifying Commands To Be Executed Each Time MPEX Is
Entered" in the Running MPEX section of this manual).

%WARNF will not work on non-HP terminals, or on really old HP terminals (like
the 2621 or the 264x series) -- it will either display the message on the
normal part of the screen, with some garbage characters before it, or might
(for non-HP terminals) trigger some strange terminal-specific behavior.  Be
careful.


_WHEREIS_970
%WHEREIS

Syntax:   %WHEREIS command

Examples: %WHEREIS EDITOR
          ----- EDITOR      MPE command
                EDITOR      Program file in PUB.SYS

          %WHEREIS MPEX@

          ----- MPEX        System-level UDC in MPEXUDC.PUB.VESOFT
                MPEX        Program file in PUB.VESOFT

          ----- MPEXHELP    MPEX command

          ----- MPEXLDIR    Command file in PUB.SYS

          ----- MPEXMGR     Command file in WORK.VESOFT
                MPEXMGR     Command file in PUB.VESOFT

          ----- MPEXSTOR    MPEX command

          ----- MPEXUDC     Command file in PUB.VESOFT

This command takes the name of a command as its parameter and displays how MPEX
would interpret the name if it were issued as a command.  WHEREIS uses the same
rules that MPEX uses at execution time to determine how a command is executed.
The command identifies all instances of the command that exist, the first one
shown is the one that would actually be executed.

The command parameter accepts wildcards, as shown in the second example.

The command is useful if MPEX appears to execute a different command from the
one you intended.  It shows you if you have conflicts between the names of your
UDCs and command files, and also if your HPPATH gives you access to the
commands that you expect it to.

MPEX uses the following precedence when determining which command to execute:

    1) MPEX aliases
    2) User-level UDCs
    3) Account-level UDCs
    4) System-level UDCs
    5) MPEX commands
    6) MPE commands
    7) temporary programs or command files in your HPPATH.
    8) permanent programs or command files in your HPPATH.

If the command parameter includes wildcard characters, all matching commands
will be displayed.  However, MPE commands are not shown when wildcard
characters are used.


_WHILE______ENDWHILE__971
%WHILE ... %ENDWHILE

Syntax:   %WHILE logicalexpression [DO]
          %>command1
          %>command2
           ...
          %>commandN
          %ENDWHILE

Example:  %SETVAR I 0
          %WHILE I<10
          %>BUILD TEST!I
          %>SETVAR I I+1
          %>ENDWHILE

The %WHILE loop executes a sequence of commands while a certain condition is
true (much like a PASCAL's WHILE loop).  For instance, the above example will
execute the commands

   %>BUILD TEST!I
   %>SETVAR I I+1

10 times, with the variable I being set to values from 0 to 9.  Once the
%>SETVAR sets I to 10, the condition "I<10" will no longer be true, and the
%WHILE loop execution will stop.  In other words, the commands actually
executed will be:

   BUILD TEST0
   SETVAR I I+1
   BUILD TEST1
   SETVAR I I+1
   ...
   BUILD TEST9
   SETVAR I I+1

Note that when you're being prompted for %WHILE loop commands, MPEX will prompt
you with "%>" instead of just "%".

%WHILE is much like MPE/iX's :WHILE command, but it gives you the full power of
VESOFT expressions (for details, see Appendix)! Here's a sample job stream
using %WHILE:

   !JOB JOBA,MGR.PROD
   !COMMENT
   !COMMENT  All MGR.PROD files that have the following lines
   !COMMENT  will only be allowed to run one at a time.
   !COMMENT
   !RUN MAIN.PUB.VESOFT;PARM=1
   %WHILE MPE ("BUILD FLAGFILE; CODE=!HPJOBNUM; DISC=1")<>0 DO
   %   COMMENT The following IF is in case the job that built
   %   COMMENT FLAGFILE aborts before PURGEing it.
   %   IF JSCOUNT("#J"+"![VEFINFO('FLAGFILE').INTCODE]")=0 THEN
   %      PURGE FLAGFILE
   %   ELSE
   %      PAUSE 300
   %   ENDIF
   %ENDWHILE
   %EXIT
   ...
   !PURGE FLAGFILE
   !EOJ


_WITHCAPS_972
%WITHCAPS

Syntax:   %WITHCAPS "caplist", command

Examples: %WITHCAPS "SM", COPY F1,F2.PUB.ACCT;YES
          %WITHCAPS "OP", STORE @.@.@; *TAPE
          %WITHCAPS "AM", NEWGROUP !GROUPNAME

Special note: although this feature is being described in the MPEX User Manual,
it is only available in MPEX command files if you are a user of both MPEX and
SECURITY.  It is also available within STREAMX jobs (for ::commands) and in
SECURITY menus.

Often you might want to have users execute certain commands in command files,
job streams, or menus, that require more capabilities than they have.  For
instance, you might want a menu to access -- in a controlled way, of course --
a file that you normally wouldn't let your users access; or, you may want to
set up an MPEX command file that lets users who lack SM capability build new
accounts, provided that certain checks are satisfied (e.g.  the new accounts
don't have unusual capabilities).  The WITHCAPS feature makes this possible.

Another similar SECURITY feature is the $NOPASS facility for STREAMX job
streams, (see "Allowing People To STREAM Certain Files Without Password
Prompts" in the Batch Access Security And Job Stream Programming section of the
SECURITY User Manual) which lets users stream jobs that log on as user IDs
whose passwords the submitting users don't know -- a user is thus allowed to
perform a particular operation that requires a given capability (for WITHCAPS)
or logs on as a given user ID (for $NOPASS) without in general having that
capability or being able to use the given user ID.  The command file, menu, or
job stream involved can then perform the proper security checks to make sure
that the high-capability operation that it's trying to perform is actually
legitimate.

The way the WITHCAPS mechanism works is rather simple:


_WITHCAPS_PERMIT_973
$WITHCAPS-PERMIT


_WITHCAPS_FORBID_974
$WITHCAPS-FORBID
   * You add lines to the STREAMX.DATA.VESOFT file that indicate which command
     files/menus/job streams being executed by which users can get which
     capabilities.  For instance, saying

       $WITHCAPS-PERMIT @.AP APPFILE.CMD.SYS "SM"

     means that the file APPFILE.CMD.SYS can use a WITHCAPS command to
     temporarily obtain SM capability -- but only while executing the
     particular line that contains "WITHCAPS", and only when executed by users
     in the AP account.  You can, of course, have multiple $WITHCAPS-PERMITs,
     but you can also restrict them by using $WITHCAPS-FORBIDs, e.g.

       $WITHCAPS-PERMIT @.AP @.CMD.SYS "AM"
       $WITHCAPS-FORBID CLERK.AP NEWUSER.CMD.SYS "AM"

     which lets all AP users use all CMD.SYS files that acquire AM capability,
     but forbids CLERK.AP from using NEWUSER.CMD.SYS, a command file that would
     need AM capability to add a new user to the system, for instance.

     Needless to say, it's very important that you've thought out all the
     security ramifications of letting these users use the files which
     temporarily get extra capabilities.  In particular, it is, of course,
     vital that users not have write or save access to the filesets specified
     in $WITHCAPS-PERMIT, since otherwise they'd be able to make up their own
     files with WITHCAPS commands in them.

   * Once the appropriate $WITHCAPS-PERMIT line has been added to the
     STREAMX.DATA.VESOFT file, the job stream, menu, or command file would then
     include a

        ::WITHCAPS "caplist", cmd   in a STREAMX job
        or
        WITHCAPS "caplist", cmd     in a SECURITY menu or an MPEX command file

     For example,

        WITHCAPS "SM", COPY F1,F2.PUB.ACCT;YES

     will execute the COPY command while possessing "SM" (and will, of course,
     reset the capabilities to normal when done).  A menu option using this
     might look like:

        *CAPTION ADD RECORD TO CONTROL FILE
        PROMPT STRING REC = "Enter record"; &
               CHECK = (REC[0:1]<>"A" and REC[0:1]<>"D"); &
               CHECKERROR = "Not allowed to add Add or Delete records"
        WITHCAPS "SM", CALC VEFWRITE ('CONTFILE,OLD;ACC=APPEND', REC)

     Similarly, an MPEX command file (or UDC) might have a %WITHCAPS a STREAMX
     job might have a ::WITHCAPS.  Note that the STREAMX ::WITHCAPS will change
     capabilities at job submission time (for the benefit of any :: commands
     that you might want to do), not at job execution time (since you can
     already determine the job execution capabilities by submitting the job
     under the right user ID).


WITHCAPS_975
WITHCAPS
You need to keep a few things in mind when you use WITHCAPS:

   * Firstly, be careful what you do when you've gotten capabilities with
     WITHCAPS.  For instance, don't just do an operation on a file whose name
     the user gave you (as a parameter or an input value) -- check to make sure
     that the user is really allowed to manipulate this file.  Don't just
     create a new user with the parameters that the user specified; check to
     make sure that, for instance, the capability list doesn't include SM, AM,
     OP, or PM.

   * The WITHCAPS takes effect only for the MPEX/LOGON/STREAMX process and for
     processes the command passed to WITHCAPS starts up.  Since we don't set
     the capabilities for the whole session (for security reasons), some
     operations (VEJOBINFO, for example) and programs might not recognize the
     temporarily acquired capabilities, though we believe that most (including,
     most importantly, the file system's file security checking) will.

   * Normally, when you run a program or execute a command file, MPEX (and MPE)
     first try to find a temporary file with that name and only look for a
     permanent file if the temporary file doesn't exist.  This would make it
     possible for a user to violate security by creating a temporary file with
     the same name as a command file or program that was to be executed while a
     WITHCAPS was in effect.  To avoid this, MPEX, LOGON, and STREAMX will,
     while a WITHCAPS is in effect, only execute permanent command files and
     programs (unless you explicitly indicate otherwise in the command
     file/menu/job stream by using a file equation with a ,OLDTEMP on it).

   * By the same token, we do not execute UDCs when WITHCAPS is in effect.  The
     reason for this is that the operating system resolves UDCs by scanning the
     USER level UDCs first, then the ACCOUNT level and finally the SYSTEM
     level.  If we were to execute UDCs while a user had additional
     capabilities, all a user would have to do to circumvent security would be
     to set a USER level UDC with the same name as an ACCOUNT or SYSTEM level
     UDC or even an MPE command -- therefore we don't allow this.

   * Also for security reasons, MPEX will not honor MPEXCRITRESTRICTxxx
     variables (which restrict MPEX fileset handling commands to operate only
     on certain types of files) and VESOFTDEFAULTxxx variables (which set
     defaults for %ALTFILE, %COPY, %PRINT, :PREP, :RUN, :PREPRUN, and implied
     RUN parameters) while a WITHCAPS is in effect.

   * You cannot use WITHCAPS to acquire PM, PH, MR, DS, IA, and BA
     capabilities; fortunately, you probably wouldn't want to, since the most
     useful capabilities to acquire are SM, AM, and OP, and possibly also AL
     and GL.

   * As we said before, this feature is only available in MPEX if you are user
     of SECURITY.


_XEQ_976
%XEQ

Syntax:   %XEQ commandfilename [parameterlist]
          %XEQ progfilename [[INFO=]infostring] [;[PARM=]parmvalue]

Examples: %XEQ MYPROG INFO="MYFILE";PARM=%10001
          %XEQ MYPROG "MYFILE",%10001

In principle, "%XEQ xxx yyy" does the same thing as "%xxx yyy" -- it finds a
program file or a command file named "xxx" and executes it, passing to it the
parameters "yyy".  (See "Implied RUN" and "Command Files" in the MPEX Commands
chapter for more details.)

Why have the %XEQ command at all? The only reason for it is if "xxx" happens to
be the name of an MPE or MPEX commands or a UDC.  Remember that the sequence in
which MPEX tries to execute commands is:

   * UDCs,

   * MPEX commands,

   * built-in MPE commands,

   * and finally command files or implied :RUNs.

If the command file or program you want to execute has the same name as a UDC
or an MPE or MPEX command (e.g.  "INPUT" and "FCOPY" in the examples above),
you need to use the %XEQ command.

Note that %XEQ honors the HPPATH variable just like normal command file
execution and implied :RUNs do.


Version_25__compatibility_issues__977
Version 25. compatibility issues

The following is a list of everything that we believe could be considered an
"incompatibility" with the previous major release of MPEX.  We don't believe
any of these changes should have negative impact on you, but we want to make
you aware of them.

For more details on any of these features, please see the main entry for that
feature in the MPEX User Manual.

***  IMPORTANT NOTE FOR USERS OF MPE/iX 4.5:


IMPORTANT_NOTE_FOR_USERS_OF_MPE_iX_4_5_978
IMPORTANT NOTE FOR USERS OF MPE/iX 4.5

Version 4.5 of the MPE/iX operating system was the first version to include
POSIX-compliant extensions, and was sent primarily to software developers and
users specifically interesting in Beta testing these extensions.  MPE/iX
version 5.0 is the first generally distributed version to include POSIX
extensions.  Because of a number of limitations in MPE/iX 4.5, with the release
of 5.0 we no longer support version 4.5 of the operating system.

***  VISUAL VEMODIFY (FOR %REDO) EXTENDS BEYOND 1 SCREEN LINE


Visual_VEMODIFY__979
Visual VEMODIFY

The VEMODIFY function, used for %REDO and HOOKed programs, when editing in
visual mode, has been enhanced to allow lines containing up to 150 characters
to be edited.  Characters inserted on the first line will insert-wrap to the
second line when they reach the last screen column, and characters deleted from
the first line will pull back characters from the second line.

By default, VEMODIFY assumes that your terminal is 80 columns wide, and uses
cursor-positioning escape sequences that won't work correctly if you have a 132
column wide terminal.

If you switch between 80 and 132 character-wide modes, you can now configure
VEMODIFY to use width-independent escape sequences to position the cursor.  To
do this you must setup the JCW VESOFTVEMODIFYEXPANDOK=1 before using VEMODIFY
the first time, or issue the %INITREDO command after setting the JCW.

VEMODIFY uses much longer escape sequences when you configure it this way, so
we suggest you only use this mode when connected over a high speed line.

Type "%HELP VEMODIFY" for more details on this topic

***  USING THE CONTINUE ("&") CHARACTER


Compatibility__Using_the_CONTINUE__980
Compatibility: Using the CONTINUE

MPEX handles continuation lines the same way MPE does on a CLASSIC system, i.e.
there will be one space inserted where the continuation character appears in
the line.  MPE/iX however, does not insert a space, and also strips any leading
spaces from the next line.  In order to make MPEX behave the same way, you must
set the JCW VESOFTCONTINUENOSPACE=1.  Be aware that this may cause files that
worked before to fail.  For example, the following IF command will fail:

IF a=b AND&
   j=k THEN
  ECHO Test true
ENDIF

as the letter "j" will be appended to the "AND" operator.  Both MPEX and MPE/iX
will report an error when trying to evaluate the variable "ANDj".

Type "%HELP CONTINUE" for more details on this topic

***  "@.@.@"  VS. "/" ON SYSTEMS THAT SUPPORT POSIX


Compatibility__________vs______on_POSIX_systems_981
Compatibility: "@.@.@" vs. "/" on POSIX systems

Historically, "@.@.@" meant every file on the system.  With the release of
MPE/iX 4.5, however, it became necessary to use "/" to specify all files on the
system.  ("@.@.@" was limited to all MPE files on the system -- files stored in
subdirectories under the root or other MPE groups would not qualify as part of
"@.@.@".)

With the release of MPE/iX 5.0, MPE's :STORE command was modified to treat
"@.@.@" and "@.@.MYACCT" as equivalent to "/" and "/MYACCT/" respectively.
This is currently the only HP supplied utility that acts in this manner -- the
:LISTF command only list MPE files, and the :LISTFILE command only lists POSIX
files if you specify a POSIX-syntax fileset (one beginning with a "." or "/").
Other HP commands and utilities act in a similar manner, i.e.  only finding
files in the MPE or POSIX namespace depending upon the fileset given in the
command.

MPEX commands that accept filesets, however, will accept either a POSIX style
fileset, an MPE style fileset, or a mixture of MPE and POSIX filesets and
automatically format the output as appropriate.  In addition, %LISTF @.GROUP
will display any POSIX filenames stored in that group (but not in any
subdirectories of that group).

Type "%HELP HFS" or "%HELP POSIX" for more details on this topic

***  LISTF FORMAT CHANGES


Compatibility___LISTF_format_changes_982
Compatibility: %LISTF format changes

A number of extensions have been made to the output of MPEX's %LISTF modes (on
both POSIX and pre-POSIX systems), as summarized below:


Compatibility__VESOFTNOTALWAYSPOSIX_983
Compatibility: VESOFTNOTALWAYSPOSIX
All %LISTF modes:

  On POSIX system, unlike the MPE/iX :LISTF command, the MPEX %LISTF command
  shows all POSIX files, including lower and mixed-case filenames, filenames
  containing special characters, and long filenames.

  If you wish to inhibit the display of all POSIX files (and emulate the
  behavior of MPE's :LISTF command), issue the following command:

    %SETVAR VESOFTNOTALWAYSPOSIX TRUE


Compatibility__MPEXLISTFLABELSIZE_984
Compatibility: MPEXLISTFLABELSIZE
%LISTF ,-1:

  On POSIX systems, the output of %LISTF,-1 has been extended to display 332
  words of the filelabel, as opposed to the 256 words displayed by the MPE/iX
  :LISTF,-1.

  If you wish to emulate the behavior of MPE's :LISTF command, issue the
  following command:

    %SETVAR MPEXLISTFLABELSIZE 256


Compatibility__MPEXLISTFNODAYS_985
Compatibility: MPEXLISTFNODAYS
%LISTF ,2:

  The output of %LISTF,2 has been extended to display the number of days since
  a file was last accessed and modified.  The new fields are displayed to the
  right of the traditional :LISTF,2 fields.

  If you wish to inhibit the display of the two new fields, issue the following
  command:

    %SETVAR MPEXLISTFNODAYS TRUE


Compatibility__Changes_to__LISTF_986
Compatibility: Changes to %LISTF
%LISTF ,-3 and %LISTF ,3:

  The output of %LISTF ,3 and %LISTF ,-3 has been modified on POSIX systems to
  include information on a file's OWNER and GROUPID.  In addition MPEX's %LISTF
  also reports the numeric UID and GID equivalents (when the filename is
  specified using HFS-syntax), as well as the POSIX State-Change timestamp, and
  the target filename of a link file.

  The '**SECURITY IS ON' field now also indicates if a file has an ACD
  assigned, and shows (on POSIX systems) if the ACD is required.

  On Spectrum systems, volume restrictions are now accurately displayed, as
  well as an indication if the file is a system bootfile, located on device
  $SYSTEM_MASTER.

***  FILE ATTRIBUTES: CREATOR, CREATORACCOUNT, AND OWNER


Compatibility__CREATOR_and_OWNER_file_attributes_987
Compatibility: CREATOR and OWNER file attributes

There are two new attributes related to the CREATOR attribute, these are
CREATORACCOUNT and OWNER.  The CREATOR is the MPE USER ID of the owner of the
file, (just as it has always been), while the CREATORACCOUNT is the MPE ACCOUNT
name of the owner of the file and the OWNER is both the CREATOR and
CREATORACCOUNT attributes in the form "user.account".

When CREATOR is used within extended fileset selection, special logic is used
to allow it to match either the traditional "user" or the new "user.account"
posix styles of representing the file creator.  When OWNER is used within
extended fileset selection, it will only match strings using the "user.account"
format.

In other words, (CREATOR="MANAGER.SYS") works just as well as
(OWNER="MANAGER.SYS"), (CREATOR="CLERK") works the same as it always has, while
(OWNER="CLERK") will never match anything.

When these attributes are recovered using the VEFINFO(..) function, CREATOR
just returns the USER info while OWNER returns both the user and account.  This
is very useful when trying to determine if the creator of a file still exists.
In the %ALTFILE section, we gave this example:

   %ALTFILE @.@(NOT USEREXISTS(CREATOR+"."+ACCOUNT));CREATOR=MANAGER

Using the OWNER attribute instead, this can be simplified as follows:

   %ALTFILE @.@(NOT USEREXISTS(OWNER));CREATOR=MANAGER.ACCT

Type "%HELP CREATOR" for more details on this topic

***  EXTENDED FILESETS USING CREATOR= AND CODE=


Compatibility__using_CREATOR__in_extended_filesets_988
Compatibility: using CREATOR= in extended filesets

In order to be compatible with older versions of our software, version 2.4 of
our software automatically quoted the value specified for CREATOR and CODE when
used in an extended selection.  A warning was issued, however, that we were
doing this and that at some point in the future this might change.  This is
inconsistent with the rest of our software as these attributes are defined as
STRING attributes, but could not be compared to STRING variables.  (Since we
were automatically quoting the comparison value, using the name of a string
variable would not work as we would try to quote the name of the variable
instead of comparing the CREATOR or CODE to the VALUE of the variable.)

For version 25., when we see an extended selection of (CREATOR=MYVAR), we will
first check to see if there is a (string) variable called MYVAR and if so, use
the value of the variable for the comparison.  If MYVAR doesn't exist, then we
will issue the old warning and search for files created by the user "MYVAR".

For the CODE attribute, however, we treat valid values as reserved words and
issue the warning that you should use a quoted value.  For instance:

   %SETVAR A "BASFP"
   %LISTF @.SOURCE(CODE=A)

will work, but

   %SETVAR BASFP "BASFP"
   %LISTF @.SOURCE(CODE=BASFP)

will generate a warning message.

***  ERRORS AND WARNINGS IN STDLIST(..) HONOR I/O REDIRECTION


Compatibility__STDLIST_989
Compatibility: STDLIST

In prior versions, errors or warnings detected during execution of the
STDLIST(..) function would ALWAYS display on your terminal, even if the
"command" in the STDLIST(..) function had I/O redirection specified.  In
version 25., errors or warnings will be directed to any I/O redirection file as
specified in the STDLIST(..) function call.

For example:

   %SETVAR XFILE STDLIST("SHOWVAR BADVARIABLENAME >MYFILE")

would display an error message in 2.4, even though the "result" of the SHOWVAR
command was being redirected.  In version 25., the file MYFILE will actually
contain the text of the error message.  This will only effect you if you expect
the file to be empty if there is an error.  In both versions, however, the
variable HPCIERR is set to indicate whether or not an error occurred in the
command passed to the STDLIST(..) function.

Type "%HELP STDLIST" for more details on this topic

***  ISxxxCAP VARIABLES/FUNCTIONS FIXED


Compatibility__ISxxxCAP_variables_functions_fixed_990
Compatibility: ISxxxCAP variables/functions fixed

In previous versions, some ISxxxCAP variables would return a 1 or 0 instead of
TRUE or FALSE as documented.  These still worked in an extended selection as we
treated a 1 as TRUE and 0 as FALSE, but direct comparisons would fail.  If you
worked-around this problem in a job stream or command file, you will have to
fix your files to compare against TRUE or FALSE as appropriate.

Type "%HELP ATTRIBUTE" for more details on this topic

***  NOTEPADS AND MPEXPREFIXDEF59 (;)


Compatibility__NOTEPADS_AND_MPEXPREFIXDEF59__991
Compatibility: NOTEPADS AND MPEXPREFIXDEF59

Setting MPEXPREFIXDEF59, (the ";"), will override our new NOTEPAD feature.  If
you have set a prefix definition variable for the semicolon, then you must set
the VESOFTPREFIXNOTE variable to a different (unused) special character if you
wish to make use of this new feature.

Type "%HELP NOTEPAD" for more details on this topic

***  %ABORTJOB SCHED CAN ABORT STREAMX SCHEDULED JOBS


Compatibility___ABORTJOB_can_abort_STREAMX_SCHED_jobs_992
Compatibility: %ABORTJOB can abort STREAMX SCHED jobs

The scope of the SCHED job attribute has been extended to encompass both MPE
scheduled jobs and STREAMX scheduled jobs (STREAMX SCHEDULING features --
repetitive and conditional job submission --- are described in the SECURITY
MANUAL.)

As a result of this change, issuing the MPEX command %ABORTJOB SCHED will now
result in the loss of all STREAMX scheduled jobs (including the specification
of when the job is to be launched).

If you wish to limit the scope of SCHED to MPE scheduled jobs only, you should
use the MPEX command %ABORTJOB @J&SCHED instead.

Type "%HELP ABORTJOB" or "%SEC HELP STREAMX" for more details on this topic

***  %ALARM STARTS THE BACKG JOBSTREAM IF IT IS NOT ALREADY RUNNING


Compatibility___ALARM_starts__BACKG_if_not_running_993
Compatibility: %ALARM starts %BACKG if not running

The %ALARM command will start the %BACKG background jobstream if the job is not
already running.  Although this is the normal behavior for SM or OP users, the
%ALARM command has been enhanced to start the BACKG job (if necessary) when
used by ANY user.  However, if the %ALARM command starts the background job,
then only the %ALARM task is started -- any other "pending" tasks remain
pending until a normal %BACKG STARTJOB command is issued.

Type "%HELP ALARM" or "%HELP BACKG" for more details on this topic

***  %ALTFILE program;CAP=-xx,yy,zz CHANGED


Compatibility___ALTFILE_program_CAP_____changed_994
Compatibility: %ALTFILE program;CAP=+/- changed

When using ;CAP= on an %ALTFILE or %COPY command, "-" signs do not need to be
repeated.  i.e., ;CAP=PH,-MR,DS is equivalent to ;CAP=+PH,-MR,-DS.  The
previous version of our software treated all unsigned capabilities as having an
implied "+", i.e.  it would have ADDED PH and DS while REMOVING MR.  Similarly,
specifying ;CAP=-BA,PM,PH,+MR,DS would be treated as ;CAP=-BA,-PM,-PH,+MR,+DS.
In other words, unsigned capabilities retain the same sign as the previous
capability listed.

Type "%HELP ALTFILE" for more details on this topic

***  %ALTFILE ;CREATOR CHANGES ON POSIX SYSTEMS


Compatibility___ALTFILE__CREATOR_Changes_for_POSIX_995
Compatibility: %ALTFILE ;CREATOR Changes for POSIX

MPEX has traditionally allowed a file's CREATOR to be changed to any value,
regardless of whether the user name specified actually exists on your system.
On POSIX systems MPE/iX has it's own :ALTFILE command, which allows a file's
OWNER (and GROUPID) to be changed to any User (and Account) that are currently
configured on your system.

To maintain compatibility with MPE/iX, when used on a POSIX system, MPEX's
%ALTFILE command will now check that supplied CREATOR names actually exist, and
will fail if they don't.  If you need to use %ALTFILE to set a file's CREATOR
or GROUPID to values that don't currently exist on a POSIX system, use the new
;NOCHECK keyword.

For example, if the following ALTFILE command fails as shown:

%ALTFILE file; CREATOR=MISSING.SYS
Specified owner does not exist in the user database.  (CIERR 820)

Then you can force this to work as follows:

ALTFILE file; CREATOR=MISSING.SYS ;NOCHECK

***  %SET CREATORPROTECT NOW ENFORCED ON POSIX SYSTEMS


Compatibility___SET_CREATORPROTECT_enforced_for_POSIX_996
Compatibility: %SET CREATORPROTECT enforced for POSIX

MPEX's default behavior has always allowed users of any capability level to use
the %ALTFILE command to change the CREATOR of any file that they have read and
write access to.  The %SET CREATORPROTECT command allowed system managers
unhappy with this default to prevent ordinary users from changing CREATOR names
on any file, and to prevent account managers from altering files outside their
account.  With MPE/iX 5.0, MPE/iX has it's own :ALTFILE command, which only
allows users with appropriate privileges to change the fully-qualified OWNER of
a file.

To maintain compatibility with MPE/iX, when used on a POSIX system, MPEX now
always enforces %SET CREATORPROTECT.  The error messages displayed if a user
fails in an attempt to change a file's CREATOR name have also changed to be
compatible with MPE/iX.

Type "%HELP CREATORPROTECT" for more details on this topic

***  VEFxxx FUNCTIONS, CHANGES FOR SM USERS


Compatibility__VEFxxx_functions_997
Compatibility: VEFxxx functions

SM users can now access PRIV files using the VEFxxx functions.  When the
correct file code is specified as part of the file parameter of the VEFOPEN,
VEFREAD, and VEFWRITE functions, an SM user can open, read, and write PRIV
files.

WARNING: PRIV files are privileged for a reason! Writing to PRIV files (IMAGE
Database files, for example), may corrupt the internal structure of the file
and make them useless to your application.  Use this feature with care --
VESOFT, Inc.  cannot repair files corrupted (whether PRIVileged or not) by
misuse of these functions.

***  %MPE ERROR MESSAGES DOWN-SHIFTED


Compatibility__MPE_error_messages_down_shifted_998
Compatibility: MPE error messages down-shifted

To remain compatible with MPE/iX 5.0, we have down-shifted the text associated
with many of the MPE error messages that MPEX displays.  Users on pre-MPE/iX
5.0 releases will notice that many (but not all) of the messages we display are
now down-shifted.

***  EXPRESSIONS: TYPEOF(...) ENHANCED FOR SPECIAL TYPES


Compatibility__EXPRESSIONS__TYPEOF_999
Compatibility: EXPRESSIONS: TYPEOF

The TYPEOF(...) function has been enhanced to recognize MPEX types of REAL,
DATE, and TIME.  These types return 101, 102, and 103 respectively.  Note that
these values are returned only if the argument to the function is an EXPRESSION
and not a simple variable.  Also, setting the result of an expression to a
variable will still convert the result into a STRING for these types of
expressions, so:

   %CALC TYPEOF(TODAY+10)

would produce a different result than:

   %SETVAR TESTDATE TODAY+10
   %CALC TYPEOF (TESTDATE)

***  QEDIT "JUMBO" FILES SUPPORTED BY %PRINT & %LISTF,ID


QEDIT__jumbo__files_supported_1000
QEDIT "jumbo" files supported

Version 4.3 of Robelle's QEDIT editor supports extended size QEDIT files, known
as "jumbo" files.  These files may contain up to 1000 characters per line, and
be over 65,535 lines long.  Previous versions of MPEX were not able to
correctly display the contents of these files (which have the same "111"
filecode as standard QEDIT files).

This version of MPEX fully supports these "jumbo" files: the %PRINT command
understands their internal format, and %LISTF,ID correctly displays their
logical line length, file size and file type.  We've also added two new file
attributes: ISQEDIT qualifies all QEDIT files, ISJUMBO qualifies "jumbo" QEDIT
files only.

 *  HPREDOSIZE variable changed to MPEXREDO

There are several options you can set for the REDO facility (which apply
equally to the REDO facility available from MPEX HOOKed programs).  They are
set by defining various specially-named JCWs and/or variables.  These JCWs must
be set before issuing a %INITREDO command or running a HOOKed program within
which you wish them to take effect.

In prior versions of our software, the variable that you would use to set the
size of the history file was HPREDOSIZE -- the same variable MPE/iX uses.
However, due to the way MPE/iX handles the HPREDOSIZE variable, setting
HPREDOSIZE outside of MPEX has no effect, so we now use the variable
MPEXREDOSIZE.  Setting HPREDOSIZE inside MPEX is translated to MPEXREDOSIZE, so
users who set HPREDOSIZE in their MPEXMGR files prior to issuing the %INITREDO
command will not experience any problems.

INTRODUCTION


Appendix__VESOFT_Expressions__1001
Appendix: VESOFT Expressions

In a number of places, we talk about "expressions".  These expressions are very
powerful things; they let you do various tests, calculations, date arithmetic,
and so on.  They support a number of different data types, operators, and
functions, and may be used to process strings, integers, dates, times, boolean
conditions, and even real numbers.


Operator_precedence_1002
Operator precedence
In the simplest case, an expression is very much like an expression in BASIC,
COBOL, PASCAL, etc.  For instance,

    1+2*3+4

comes out exactly the way you expect it (11); the normal precedence of the
operators is respected (* first, then +).  Similarly,

    LEN("FOOBAR")

calculates the length of the string "FOOBAR" (which is 6);

    UPS("Testing")

returns "TESTING", the upshifted value of the string "Testing";

    MIN(123,456)

returns 123, the minimum of MIN's parameters (123 and 456).

VARIABLES


Variables__1003
Variables

In addition to the functions (MIN, UPS, LEN, etc.), the operators (+, -, *, /,
etc.), and the constants (123, "Testing", etc.), you can also use variables.
Variables are what make expressions so very powerful because they're adapted to
the program in which they're used:

   * In MPEX selection criteria and LISTF template files, you can refer to
     variables that represent various attributes of the current file (e.g.
     CODE, SECTORS, ACCDATE, etc.); for instance, an MPEX selection criterion
     may say

         ISPROG and ACCDATE<1/1/1997

   * In MPEX's %CALC, %SETVAR, and %IF (the MPE :IF command, executed within
     MPEX) you can refer to any JCW, any variable previously set by a %SETVAR,
     and any one of a number of predefined variables (described later on in
     this appendix) that let you figure out things like the logon user ID, the
     logon account, the current day of week, the current job or session limit,
     etc.

   * In SECURITY's LISTLOG and LISTUSERS options, you can refer to various
     fields of the SECURITY log record and SECURITY user record, respectively.
     For instance, you might try to find all log or user records that match the
     criterion

        USER MATCHES "X@" and ACCOUNT<>"SYS"

   * In STREAMX, you can refer to any JCW, any predefined variable (see below),
     AND any variable set by a STREAMX ::PROMPT or ::ASSIGN command.  Thus, a
     STREAMX CHECK= expression might say

         RPTCODE='XX' or RPTCODE='Y7' or RPTCODE[0:1]='Z'

     where RPTCODE is the name of the variable being ::PROMPTed for.

The differences between the kinds of variables acceptable to the different
programs are intentional, since in each case expressions have different
purposes -- sometimes to operate on file attributes, sometimes to select log
records, sometimes to work on STREAMX variables.

DATA TYPES


Data_types__1004
Data types

In the examples we showed above, we saw three data types:


Integer_variables_and_constants_1005
Integer variables and constants
   * INTEGERS.  These are simple numbers from -2147483648 to +2147483647 (i.e.
     32-bit, or "DOUBLE" integers).  You can specify them as decimal, as octal
     (prefixed by a %, e.g.  %12345670), or as hexadecimal (prefixed by a $,
     e.g.  $89ABCDEF).


String_variables_and_constants_1006
String variables and constants


Embedded_quote_characters__1007
Embedded quote characters
   * STRINGS.  These are sequences of characters -- string constants can be
     enclosed in either double quotes ("ABC") or single quotes ('ABC') although
     the quote types must obviously match (e.g.  "ABC' and 'ABC" are both
     invalid).  You may embed quotes into a quoted string by specifying the
     quote character twice, e.g.  "ABC""DEF" stands for the string ABC"DEF, and
     'ABC''DEF' stands for the string ABC'DEF; however, "ABC''DEF" stands for
     the string ABC''DEF.  The empty string (length 0) is "" (or '').


Date_variables_and_constants_1008
Date variables and constants


4_digit_years_in_dates_1009
4-digit years in dates
   * DATES.  These are dates from 1 January 1901 to 31 December 1999 with a
     2-digit year, or from 1 January 1600 onward into the next century with a
     4-digit year.  Anywhere that you can input a 2-digit year, you can also
     input a 4-digit year!

     Anytime you are prompted for a date (e.g.  by ::PROMPT in STREAMX jobs,
     PROMPT in VEMENUs, or the READDATE function) and in the DATEPARSE and
     VALIDDATE functions, you can enter it either with or without slashes
     ("/"); however, when you are specifying a date constant in an expression
     (rather than being prompted for it), you must include the slashes (to
     distinguish it from an integer).

     Date constants are usually (in STREAMX and SECURITY) specified in
     [YY]YY/MM/DD format (e.g.  90/12/21 or 2024/05/14), although they can be
     output in any format you please.  By default, date output and formatting
     are in 2-digit year format, with slashes.

     In MPEX (for historical reasons), dates are by default input in
     MM/DD/[YY]YY format (12/31/99, 11/05/2022, or even 102283), but you can
     use the %SET DATE command to change the default input format to
     [YY]YY/MM/DD or DD/MM/[YY]YY (the European way).

Several other data types are supported, too:


Boolean_variables_and_constants_1010
Boolean variables and constants
   * BOOLEAN VALUES (also known as LOGICALS).  A boolean value may be either
     TRUE or FALSE -- various operators like =, <, >, <>, >=, <=, AND, OR, NOT,
     and so on return boolean values.  In some places, e.g.  an MPEX selection
     condition, a SECURITY LISTLOG or LISTUSERS selection condition, or a
     STREAMX ::PROMPT ;CHECK= expression a boolean value is explicitly
     required; if you say in MPEX
        %!LISTF @.@.@ (2+3)
     then MPEX will print you an error message since the selection condition
     should be a boolean expression, not an integer like 2+3.


Real_variables_and_constants__1011
Real variables and constants
   * REAL NUMBERS.  Real numbers (32-bit single-precision, "HPREAL") are also
     supported -- saying

        %CALC 1.2 * 3.4

     in MPEX will give you the right value (4.08).  The range of the magnitude
     of non-zero real values is 9.9999*(10^-75) through 1.000004*(10^76); real
     numbers are accurate to 6.9 decimal places.  Real constants can be entered
     in fixed-point format (1.234) or in the exponential format known and loved
     by all you FORTRAN programmers (5.6E10).


Time_variables_and_constants_1012
Time variables and constants
   * TIMES.  You may also use the time-of-day in expressions.  (Note that
     12:00AM or 00:00T is midnight; 12:00PM or 12:00T is noon).  A time
     constant is specified by saying one of

        hour:minute AM        e.g.   10:25 AM
        hour:minute PM        e.g.    6:45 PM
        hour:minute T         e.g.   17:07 T       (24-hour clock)

     and times may be compared (RSTTIME>12:15AM) or printed.

Types are very important because the same operators (e.g.  + and -) can have
very different effects when operating on, say, integers, strings, and dates:

   10 + 20               is 30 (simple addition)
   "FOO" + "BAR"         is "FOOBAR" (string concatenation)
   91/2/20 + 10          is 91/3/2 (date increment)
   1.2 + 3.4             is 4.6 (also addition, but on real numbers)
   TRUE + FALSE          is an error (you can't add booleans);
   "FOO" + 10            is an error (you can't add numbers to strings);

Always keep in mind what types you're operating on, since that will influence
the meaning of the operation.  Also note that although all of VESOFT's programs
(MPEX, SECURITY and VEAUDIT) allow expressions of all types, not all types may
be used to define variables -- MPEX variables can only be integers, strings, or
booleans and STREAMX variables can only be integers, strings, or dates.  If you
try to set an MPEX variable to a real, date, or time value, (like 1.2,
90/11/05, or 11:59AM), the result will be converted to a string ("1.2",
"90/11/05" and "11:59AM") before assigning it to the variable -- this is for
compatibility with MPE/iX.

In all of the examples in this appendix (unless otherwise noted):

I, I1, I2, I3  are integer variables, constants, and/or expressions
B, B1, B2      are boolean variables, constants, and/or expressions
R, R1, R2      are real variables, constants, and/or expressions
S, S1, S2, S3  are string variables, constants, and/or expressions
D, D1, D2      are date variables, constants, and/or expressions
T, T1, T2, T3  are time variables, constants, and/or expressions

The type of the result returned by the various functions are indicated by (in
order of their appearance):

               [INT]  means integer
               [BOOL] means boolean
               [STR]  means string
               [DATE] means date
               [REAL] means real
               [TIME] means time
               [NONE] means this function doesn't return anything
               [???]  means the result depends on the type(s) of the
               parameter(s) passed


Integer_operators_and_functions__1013
Integer operators and functions


Boolean_operators_and_functions__1014
Boolean operators and functions

The following operators and functions work on integers and boolean values:


__1015
+

I1 + I2             [INT]     Simple addition.


__1016
-

I1 - I2             [INT]     Simple subtraction.


__1017
*

I1 * I2             [INT]     Simple multiplication.


__1018
/

I1 / I2             [INT]     Integer division, truncates result.  20/3 is 6.


MOD_1019
MOD

I1 MOD I2           [INT]     Integer remainder.  20 MOD 3 is 2.


__1020
-

-I                  [INT]     Negation.  -10 is, of course, -10.


ABS_1021
ABS

ABS (I)             [INT]     Absolute value.  ABS(-10) = 10, ABS(10) = 10.


MIN_1022
MIN

MIN (I1 [, I2...])  [INT]     Returns the smallest of one (or more) integers.


MAX_1023
MAX

MAX (I1 [, I2...])  [INT]     Returns the largest of one (or more) integers.


__1024
^

I1 ^ I2             [INT]     "I1 to the power I2".  10^3 is 1000, 2^10 is
                              1024.


RANDOM_1025
RANDOM

RANDOM (I)          [INT]     Returns a random number from 0 to I-1.


__1026
=

I1 = I2             [BOOL]    Tests whether I1 is equal to I2.


__1027
<

I1 < I2             [BOOL]    Tests whether I1 is less than I2.


__1028
>

I1 > I2             [BOOL]    Tests whether I1 is greater than I2.


___1029
<>

I1 <> I2            [BOOL]    Tests whether I1 is not equal to I2.


___1030
>=

I1 >= I2            [BOOL]    Tests whether I1 is greater than or equal to I2.


___1031
<=

I1 <= I2            [BOOL]    Tests whether I1 is less than or equal to I2.


BETWEEN_1032
BETWEEN

BETWEEN (I1,I2,I3)  [BOOL]    Tests whether I1 is between I2 and I3, i.e.
                              I1>=I2 AND I1<=I3; for instance, BETWEEN(I,1,10)
                              is TRUE if I is between 1 and 10 (inclusively).


ODD_1033
ODD

ODD (I)             [BOOL]    Tests whether I is odd rather than even.  ODD(1)
                              is TRUE, ODD(2) is FALSE.


AND_1034
AND

B1 AND B2           [BOOL]    TRUE if B1 and B2 are both TRUE.


OR_1035
OR

B1 OR B2            [BOOL]    TRUE if either B1 or B2 (or both) is TRUE.


XOR_1036
XOR

B1 XOR B2           [BOOL]    TRUE if either B1 or B2 (but not both) is TRUE.


NOT_1037
NOT

NOT B               [BOOL]    TRUE if B is false, FALSE if B is true.


__1038
&

B1 & B2             [BOOL]    Synonym for B1 AND B2.


__1039
|

B1 | B2             [BOOL]    Synonym for B1 OR B2.


TRUE_1040
TRUE


FALSE_1041
FALSE

TRUE, FALSE         [BOOL]    Boolean constants.


ON_1042
ON


OFF_1043
OFF

ON, OFF             [BOOL]    Boolean constants; ON = TRUE, OFF = FALSE.


_STARTBIT_NUMBITS__1044
[STARTBIT:NUMBITS]

I1 [I2:I3]          [INT]     Extracts I3 bits (starting with bit #I2) from the
                              integer value I1; for instance, %1234[10:3] is 3.
                              Note that the highest-order bit (since I1 is a
                              32-bit integer) is bit -16 (!) and the
                              lowest-order bit is bit 15.  This way, when you
                              extract bits from single integers, you can use
                              the 0-to-15 bit numbering; bits -16 to -1 refer
                              to the high-order word.


DBUILD_1045
DBUILD

DBUILD (I1,I2)      [INT]     Constructs a double integer with high-order word
                              I1 and low-order word I2.  DBUILD(1,2) is 65538.


HIGHORDER_1046
HIGHORDER

HIGHORDER (I)       [INT]     Returns the high-order word of I.


LOWORDER_1047
LOWORDER

LOWORDER (I)        [INT]     Returns the low-order word of I.


BNOT_1048
BNOT

BNOT I              [INT]     Returns the Bit-wise NOT of I.


BAND_1049
BAND

I1 BAND I2          [INT]     Returns a Bit-wise AND of the integers I1 and I2.


BOR_1050
BOR

I1 BOR I2           [INT]     Returns a Bit-wise OR of the integers I1 and I2.


BXOR_1051
BXOR

I1 BXOR I2          [INT]     Returns a Bit-wise XOR of the integers I1 and I2.


LSL_1052
LSL

I1 LSL I2           [INT]     Logical Shift Left the integer I1 by I2 bits.


LSR_1053
LSR

I1 LSR I2           [INT]     Logical Shift Right the integer I1 by I2 bits.


CSL_1054
CSL

I1 CSL I2           [INT]     Circular Shift Left the integer I1 by I2 bits.


CSR_1055
CSR

I1 CSR I2           [INT]     Circular Shift Right the integer I1 by I2 bits.


ASL_1056
ASL

I1 ASL I2           [INT]     Arithmetic Shift Left the integer I1 by I2 bits.


ASR_1057
ASR

I1 ASR I2           [INT]     Arithmetic Shift Right the integer I1 by I2 bits.


INTEGER_1058
INTEGER

INTEGER (S)         [INT]     Returns the value of the 16-bit integer
                              corresponding to the 2 bytes in S (if S is a
                              2-character string), or the 32-bit integer
                              corresponding to the 4 bytes in S (if S is a
                              4-character string).  Triggers an error if S is
                              neither 2 nor 4 characters long.  Useful for
                              extracting integer values from records read from
                              files using the VEFREADxxx functions.


INTEGERPARSE_1059
INTEGERPARSE

INTEGERPARSE (S)    [INT]     Converts the string S to an integer; if it's not
                              a valid integer, aborts with an error message.


VALIDINTEGER_1060
VALIDINTEGER

VALIDINTEGER (S)    [BOOL]    Returns TRUE if S is a valid integer, FALSE if it
                              isn't.


String_operators_and_functions__1061
String operators and functions

The following operators and functions work on strings:


__1062
+

S1 + S2             [STR]     Concatenates two (or more!) strings.  "AB" + "CD"
                              is "ABCD".


__1063
-

S1 - S2             [STR]     Removes the first occurrence of string S2 from
                              string S1.  "TOTO" - "O" is "TTO".


__1064
*

I * S               [STR]     Repeats I times the string S.  3*"AB" is
                              "ABABAB".


_STARTCHAR_NUMCHARS__1065
[STARTCHAR:NUMCHARS]

S [I1:I2]           [STR]     Extracts I2 characters of string S starting with
                              character #I1 (counting the first character as
                              #0); "FOOBAR"[2:3] is "OBA".


STRRTRIM_1066
STRRTRIM

STRRTRIM (S1[,S2])  [STR]     Returns S1 with all trailing occurrences of the
                              character specified by S2 (which defaults to " ")
                              removed.  STRRTRIM ("FOO   ") is "FOO";
                              STRRTRIM("ABC---","-") is "ABC".


STRLTRIM_1067
STRLTRIM

STRLTRIM (S1[,S2])  [STR]     Returns S1 with all leading occurrences of the
                              character specified by S2 (which defaults to " ")
                              removed.  STRLTRIM ("   FOO") is "FOO";
                              STRLTRIM("---ABC","-") is "ABC".


RTRIM_1068
RTRIM

RTRIM( S1[,S2])     [STR]     Same as STRRTRIM.


LTRIM_1069
LTRIM

LTRIM (S1[,S2])     [STR]     Same as STRLTRIM.


STRLDROP_1070
STRLDROP

STRLDROP (S,I)      [STR]     Returns the string S with the first I characters
                              removed.  STRLDROP("INFLAMMABLE",2) is
                              "FLAMMABLE".


STRRDROP_1071
STRRDROP

STRRDROP (S,I)      [STR]     Returns the string S with the last I characters
                              removed.  STRRDROP("ABSOLUTELY NOT",4) is
                              "ABSOLUTELY".


LEN_1072
LEN

LEN (S)             [INT]     Returns the length of string S.  LEN("NOSE") is
                              4.


POS_1073
POS

POS (S1,S2[,I])     [INT]     Returns the position of the Ith (starting with 1)
                              occurrence of S1 in S2.  If I is negative,
                              returns the position of the (-I)th occurrence of
                              S1 in S2, counting from the right.  If S1 is not
                              found in S2, returns 0.  (I defaults to 1).
                              POS("AR","SPARK") is 3;
                              POS("ISS","MISSISSIPPI",2) is 5;
                              POS("PE","PEPPERONI",-2) is 1.


UPS_1074
UPS

UPS (S)             [STR]     Returns S with all alphabetic characters
                              upshifted.  UPS("Test") is "TEST".


DWNS_1075
DWNS

DWNS (S)            [STR]     Returns S with all alphabetic characters
                              downshifted.  DWNS("Test") is "test".


STRCHANGE_1076
STRCHANGE

STRCHANGE (S1,S2,S3) [STR]    Returns the string S1 in which all occurrences of
                              the string S2 have been changed to the string S3.
                              STRCHANGE("TESTING","T","XX") is "XXESXXING".


STRCOUNT_1077
STRCOUNT

STRCOUNT (S1,S2)    [INT]     Returns the number of occurrences of S1 in S2.
                              STRCOUNT("P","Pepperoni") is 1;
                              STRCOUNT("SS","MISSISSIPPI") is 2.


RPT_1078
RPT

RPT (S,I)           [STR]     Returns string S repeated I times.  If I<0,
                              reverses string S before repeating it
                              RPT("ABC",3) is "ABCABCABC"; RPT("ABC",-3) is
                              "CBACBACBA".


CHR_1079
CHR

CHR (I)             [STR]     Returns a single-character string containing
                              ASCII character I.  CHR(33) is "!"; CHR(27) is
                              the "escape" character.


ORD_1080
ORD

ORD (S)             [INT]     Returns the integer ASCII value of the first
                              character of S.  ORD("!") is 33.


HEX_1081
HEX

HEX (I)             [STR]     Returns the value of I converted to a hexadecimal
                              string.  HEX(32767) is "$7FFF".


OCTAL_1082
OCTAL

OCTAL (I)           [STR]     Returns the value of I converted to an octal
                              string.  OCTAL(32767) is "%77777".


STR_1083
STR

STR (S,I1,I2)       [STR]     Returns I2 characters of string S starting with
                              character #I1 (counting the first as #1);
                              STR("FOOBAR",2,3) is "OOB".


LFT_1084
LFT

LFT (S,I)           [STR]     Returns the I leftmost characters of string S;
                              LFT("FOOBAR",2) is "FO".


RHT_1085
RHT

RHT (S,I)           [STR]     Returns the I rightmost characters of string S;
                              RHT("FOOBAR",2) is "AR".


ALPHA_1086
ALPHA

ALPHA (S)           [BOOL]    TRUE if S consists entirely of alphabetic
                              characters.


NUMERIC_1087
NUMERIC

NUMERIC (S)         [BOOL]    TRUE if S consists entirely of numeric
                              characters.


ALPHANUM_1088
ALPHANUM

ALPHANUM (S)        [BOOL]    TRUE if S consists entirely of alphabetic and/or
                              numeric characters.


MAXCONSECUTIVE_1089
MAXCONSECUTIVE

MAXCONSECUTIVE (S)  [INT]     Returns the maximum number of consecutive
                              occurrences of any characters in S.  Thus,
                              MAXCONSECUTIVE("ABBCCCDDE") is 3, since the
                              character 'C' occurs 3 times in a row.


__1090
=

S1 = S2             [BOOL]    Tests if S1 is equal to S2.


__1091
<

S1 < S2             [BOOL]    Tests if S1 is less than S2.


__1092
>

S1 > S2             [BOOL]    Tests if S1 is greater than S2.


___1093
<>

S1 <> S2            [BOOL]    Tests if S1 is not equal to S2.


___1094
>=

S1 >= S2            [BOOL]    Tests if S1 is greater than or equal to S2.


___1095
<=

S1 <= S2            [BOOL]    Tests if S1 is less than or equal to S2.


MATCHES_1096
MATCHES

S1 MATCHES S2       [BOOL]    Tests if S1 matches the MPE-like pattern S2,
                              where "?" character in S2 means any single
                              alphanumeric character, "#" means any single
                              numeric character, "@" means any number (0 or
                              more) of alphanumeric characters; you may also
                              use the "[...]" range operator (see "File Ranges"
                              in the MPEX User Manual).


NMATCHES_1097
NMATCHES

S1 NMATCHES S2      [BOOL]    Same as NOT (S1 MATCHES S2).


MIN_1098
MIN

MIN (S1 [, S2...])  [STR]     Returns the "minimum" of one (or more) strings.
                              "Minimum" means alphabetically, not according to
                              length, thus MIN("AAA","ZZ") is "AAA";
                              MIN("BIG","SMALL","MEDIUM") is "BIG".


MAX_1099
MAX

MAX (S1 [, S2...])  [STR]     Returns the "maximum" of one (or more) strings.
                              "Maximum" means alphabetically, not according to
                              length, thus MAX("AAA","ZZ") is "ZZ";
                              MAX("BIG","SMALL","MEDIUM") is "SMALL".


BETWEEN_1100
BETWEEN

BETWEEN (S1, S2, S3) [BOOL]   Tests whether S1 is between S2 and S3, i.e.
                              S1>=S2 AND S1<=S3; for instance,
                              BETWEEN(S,"JA","LM") is TRUE if S is between "JA"
                              and "LM" (inclusively).


TOKEN_1101
TOKEN


NTOKEN_1102
NTOKEN


REMTOKEN_1103
REMTOKEN

TOKEN (S1,S2)       [STR]     Returns the first "token" of S1, where S2 is a
                              string containing the token delimiters; a "token"
                              is the set of characters, excluding the leading
                              and trailing spaces, up to (but not including)
                              the first occurrence of any one of the
                              delimiters; e.g.  TOKEN("  ABC  /  D : EF ",
                              "/:") is "ABC".

NTOKEN (S1,I,S2)    [STR]     Returns the Ith "token" of S1, where S2 is a
                              string containing the token delimiters; e.g.
                              NTOKEN('8:49/#J8/9/LDEV# FOR "T" ON TAPE (NUM)?',
                              3, "/") is "9"

REMTOKEN (S1,S2)    [STR]     Returns the second through last "tokens" of S1,
                              where S2 is a string containing the token
                              delimiters; e.g.  REMTOKEN("  ABC  /  D : EF ",
                              "/:") is "D : EF ".

TOKEN (S1,S2,S3)    [STR]     Same as TOKEN(S1,S2), but considers S3 to be the
                              set of allowed QUOTE CHARACTERS -- delimiters
                              embedded within quotes are ignored in determining
                              token boundaries.  For instance,
                              TOKEN("  'ABC  /  D'  :  EF  ", "/:", "'") is
                              "'ABC  /  D'" -- the first "/" is not treated as
                              a delimiter because it's nested within "'" quote
                              characters.

NTOKEN (S1,I,S2,S3) [STR]     Same as NTOKEN(S1,I,S2), but supporting quote
                              characters.

REMTOKEN (S1,S2,S3) [STR]     Same as REMTOKEN(S1,S2), but supporting quote
                              characters.

[Note: The following cases are exceptions to the syntax listed above -- in
them, the second parameter is not viewed as a string of delimiters, but as
something different.]

TOKEN (S,"A")       [STR]     Returns all the characters of S until the first
                              non-Alphabetic character -- TOKEN("FOO1/3","A")
                              is "FOO".

TOKEN (S,"N")       [STR]     Returns all the characters of S until the first
                              non-Numeric character -- TOKEN("123F/O","N") is
                              "123".

TOKEN (S,"AN")      [STR]     Returns all the characters of S until the first
                              non-AlphaNumeric character --
                              TOKEN("123FOO/BAR","AN") is "123FOO".

REMTOKEN (S,"A" | "N" | "AN")

                    [STR]     Returns all the characters of S starting with the
                              first non-Alphabetic, non-Numeric, or
                              non-AlphaNumeric character, respectively --
                              REMTOKEN("FOO1/3","A") is "1/3".


Date_operators_and_functions__1104
Date operators and functions

The following operators and functions work on dates:


__1105
+

D + I               [DATE]    Date increment; returns the date that is I days
                              after D.  92/3/30 + 10 is 92/4/9).


__1106
-

D - I               [DATE]    Date decrement; returns the date that is I days
                              before D.  92/4/9 - 10 is 92/3/30).


__1107
-

D1 - D2             [INT]     Date difference; calculates the number of days
                              between D1 and D2.  92/4/9 - 92/3/30 is 10).


__1108
=

D1 = D2             [BOOL]    Tests if D1 is the same date as D2.


__1109
<

D1 < D2             [BOOL]    Tests if D1 is earlier than D2.


__1110
>

D1 > D2             [BOOL]    Tests if D1 is later than D2.


___1111
<>

D1 <> D2            [BOOL]    Tests if D1 is a different date from D2.


___1112
>=

D1 >= D2            [BOOL]    Tests if D1 is later or the same as D2.


___1113
<=

D1 <= D2            [BOOL]    Tests if D1 is earlier or the same as D2.


MIN_1114
MIN


MAX_1115
MAX


BETWEEN_1116
BETWEEN

MIN, MAX, BETWEEN             These work the same way they do for integers...


DATEBUILD_1117
DATEBUILD

DATEBUILD (I1,I2,I3) [DATE]   Returns a date with the year I1, month I2, day
                              I3; DATEBUILD(92,10,1) is thus equal to 92/10/1.
                              (The advantage of DATEBUILD over the yy/mm/dd
                              syntax is that DATEBUILD's parameters may be
                              variables.)


DATEYEAR_1118
DATEYEAR

DATEYEAR (D)        [INT]     Returns the 2-digit year number of date D (Aborts
                              if you pass it a year outside the 20th century).


DATEYEAR4_1119
DATEYEAR4

DATEYEAR4 (D)       [INT]     Returns the 4-digit year number of date D.


DATEMONTH_1120
DATEMONTH

DATEMONTH (D)       [INT]     Returns the month number of date D.


DATEDAY_1121
DATEDAY

DATEDAY (D)         [INT]     Returns the day-of-month of date D.


DATEDAYOFWEEK_1122
DATEDAYOFWEEK

DATEDAYOFWEEK (D)   [INT]     Returns the day of week (1=Sunday, 2=Monday, ...,
                              7=Saturday).


DATEADD_1123
DATEADD

DATEADD (D,I1,I2,I3) [DATE]   Returns a date that is I1 years, I2 months, and
                              I3 days after the date D.


DAYOFYEAR_1124
DAYOFYEAR

DAYOFYEAR (D)       [INT]     Returns the Julian "day of the year" for the
                              given date.


YYYYMMDD_1125
YYYYMMDD

YYYYMMDD (D)        [INT]     Converts D into an integer formatted as (4-digit
                              year) followed by (2-digit month) followed by
                              (2-digit day).  YYYYMMDD(92/3/30) is 19920330.


CDATE_1126
CDATE

CDATE (D, S)        [STR]     Formats D as a string; S specifies format.
                              CDATE(0/1/4,'YY/MM/DD')         is 00/01/04
                              CDATE(0/1/4,'MM/DD/YYYY')       is 01/04/2000
                              CDATE(0/1/4,'DD/MM/YY')         is 04/01/00'
                              The slashes may also be omitted or replaced by
                              any other character, e.g.
                              CDATE(0/1/4,'YYMMDD')           is 000104
                              CDATE(0/1/4,'DD.MM.YY')         is 04.01.00
                              Other special date descriptors may also be used
                              (see the STRWRITE function for a full
                              description):
                              CDATE(0/1/4,'%W, %1M %0D, %4Y') is TUE, JAN 04,
                              2000


CDATEYMD_1127
CDATEYMD

CDATEYMD (D)        [STR]     Formats D as a YY/MM/DD date.


CDATEMDY_1128
CDATEMDY

CDATEMDY (D)        [STR]     Formats D as a MM/DD/YY date.


CDATEDMY_1129
CDATEDMY

CDATEDMY (D)        [STR]     Formats D as a DD/MM/YY date.


DATEPARSE_1130
DATEPARSE

DATEPARSE (S1,S2)   [DATE]    Parses the string S1 as a date; S2 specifies the
                              format in which S1 is supposed to be, either
                              'YMD', 'MDY', or 'DMY'.  (The date may have
                              either a 2- or 4-digit year, and may exclude the
                              slashes).  DATEPARSE('03/30/91','MDY') is
                              91/03/30; DATEPARSE('19910330','YMD') is also
                              91/03/30.


VALIDDATE_1131
VALIDDATE

VALIDDATE (S1,S2)   [BOOL]    Returns TRUE if S1 is a valid date, FALSE if it
                              isn't -- S2 specifies the format, either 'YMD',
                              'MDY', or 'DMY'.  (The date may have either a 2-
                              or 4-digit year, and may exclude the slashes).


TODAY_1132
TODAY

TODAY               [DATE]    Returns today's date.


CALENDARTODATE_1133
CALENDARTODATE

CALENDARTODATE (I)  [DATE]    Returns the date represented by the
                              CALENDAR-intrinsic-format integer I.


DATETOCALENDAR_1134
DATETOCALENDAR

DATETOCALENDAR (D)  [INT]     Returns the CALENDAR-intrinsic-format
                              representation of the date D.


Real_operators_and_functions__1135
Real operators and functions

The following operators and functions work on reals:

Note that in any "mixed-mode" operation -- where one operand is an integer and
the other is a real -- the integer will be automatically converted to a real.


__1136
+


__1137
-


__1138
*


__1139
/


__1140
=


__1141
<


__1142
>


___1143
<>


___1144
<=


___1145
>=


ABS_1146
ABS


MIN_1147
MIN


MAX_1148
MAX


BETWEEN_1149
BETWEEN

+, -, *, /, =, <, >, <>, >=, <=, ABS, MIN, MAX, BETWEEN These work the same way
                              they do for integers...


___1150
//

I1 // I2            [REAL]    Divides two integers and yields a real number
                              (dividing two integers as I1/I2 will always yield
                              an integer); e.g.  10//3 is 3.33333.  Note that
                              R1/R2 (a real divided by a real, with one slash)
                              returns a real; two slashes are only needed when
                              dividing integers.


__1151
^

R1 ^ R2             [REAL]    "R1 to the power R2".  2.5^3 is 15.625, 2.25^.5
                              is 1.5).


ROUND_1152
ROUND

ROUND (R)           [INT]     Rounds R to the nearest integer (ROUND(1.5) is
                              2.0).


INTEGER_1153
INTEGER

INTEGER (R)         [INT]     Truncates R into an integer.


REALPARSE_1154
REALPARSE

REALPARSE (S)       [REAL]    Converts the string S to a real number; if it's
                              not a valid real number, aborts with an error
                              message.


EXP_1155
EXP

EXP (R)             [REAL]    Returns e (2.718281828) to the power R.


LOG_1156
LOG

LOG (R)             [REAL]    Returns the natural logarithm of R.


SIN_1157
SIN

SIN (R)             [REAL]    Returns the sine of R (an angle in radians).


COS_1158
COS

COS (R)             [REAL]    Returns the cosine of R (an angle in radians).


TAN_1159
TAN

TAN (R)             [REAL]    Returns the tangent of R (an angle in radians).


SQRT_1160
SQRT

SQRT (R)            [REAL]    Returns the square root of R.


REAL_1161
REAL

REAL (I)            [REAL]    Explicitly converts I to a real.


Time_operators_and_functions__1162
Time operators and functions


Time_constants_1163
Time constants
Constants of type time may be specified in one of three formats:

   hour:minuteAM              e.g.   10:25AM
   hour:minutePM              e.g.    6:45PM
   hour:minuteT               e.g.   17:07T       (24-hour clock)

For example, you might say (the function CLOCK is described below):

   CLOCK>6:00PM AND CLOCK<6:30PM

   or

   CLOCK>18:00T AND CLOCK<18:30T

If the "minute" field is 0 (e.g.  6:00PM), you can omit it and the colon, i.e.
say "6PM"; for instance,

   CLOCK>6PM AND CLOCK<7PM

Note: you must specify one of those three suffixes (to avoid ambiguity) --
"9:55" is not valid (though "9:55T" is).

The following operators and functions work on time values:


__1164
<


__1165
>


___1166
<>


___1167
<=


___1168
>=


MIN_1169
MIN


MAX_1170
MAX

=, <, >, <>, >=, <=, MIN, MAX These work the same way they do for integers...


BETWEEN_1171
BETWEEN

BETWEEN (T1,T2,T3)  [BOOL]    TRUE if T1 is between T2 and T3 (inclusively);
                              BETWEEN(CLOCK,8AM,8:15AM) returns TRUE if
                              CLOCK>=8AM and CLOCK<=8:15AM.  Note: always FALSE
                              if T2>T3; i.e.  BETWEEN(CLOCK,10PM,4AM) is always
                              false -- instead try NOT BETWEEN(CLOCK,4AM,10PM).


CLOCK_1172
CLOCK

CLOCK               [TIME]    Returns the current time.


CLOCKTOTIME_1173
CLOCKTOTIME

CLOCKTOTIME(I)      [TIME]    Converts an integer in the format returned by the
                              MPE CLOCK intrinsic to the VESOFT time format.


HHMMSS_1174
HHMMSS

HHMMSS (T)          [INT]     Formats the time T into an integer consisting of
                              (2-digit hour) followed by (2-digit minute)
                              followed by (2-digit second); HHMMSS(5:33PM) is
                              173300.


TIMEPARSE_1175
TIMEPARSE

TIMEPARSE (S)       [TIME]    Parses the string S as a time;

                                TIMEPARSE('23:00') is 11:00 PM;

                                TIMEPARSE('23:00T') is also 11:00 PM;

                                TIMEPARSE('11:00') is 11:00 AM, not PM;

                                TIMEPARSE('11:00 PM') is 11:00 PM.


VALIDTIME_1176
VALIDTIME

VALIDTIME (S)       [BOOL]    Returns TRUE if the string S contains a valid
                              time representation (e.g.  "12:34 PM"), FALSE if
                              it doesn't.


TIMEBUILD_1177
TIMEBUILD

TIMEBUILD (I1,I2,I3) [TIME]   Constructs a time value corresponding to I1
                              hours, I2 minutes, and I3 seconds.  Thus,
                              TIMEBUILD(10,5,0) is the same as 10:05AM --
                              TIMEBUILD's advantage over the hh:mmT syntax is
                              that TIMEBUILD can take variables as parameters.


__1178
+

T + I               [TIME]    Returns the time that is I seconds after time T.


__1179
-

T - I               [TIME]    Returns the time that is I seconds before time T.


__1180
-

T1 - T2             [INT]     Returns the number of seconds between T2 and T1.


Special_MPE_access_functions__1181
Special MPE access functions

These functions do special MPE-dependent things like look up your capabilities,
parse/format file codes, etc.:


CAPABILITY_1182
CAPABILITY

CAPABILITY (S)      [BOOL]    Checks if the running user has the capability
                              indicated by the 2-character string S -- e.g.
                              CAPABILITY("SM") checks if the user has SM
                              capability.


ICODE_1183
ICODE

ICODE (S)           [INT]     Parses a string that contains an MPE filecode and
                              returns the integer value of the filecode, e.g.
                              ICODE("PROG") is 1029.  Remember, "PRIV" and
                              "KSAM" are NOT filecodes (even though :LISTF,2
                              puts them in the CODE field).


SCODE_1184
SCODE

SCODE (I)           [STR]     Converts an integer value of an MPE filecode into
                              its string representation, e.g.  SCODE(1029) is
                              "PROG".


MPE_1185
MPE

MPE (S)             [INT]     Executes the MPE command indicated by S; returns
                              0 if all's well or the CI error number if an
                              error does occur.


WRITEMPEMESSAGE_1186
WRITEMPEMESSAGE

WRITEMPEMESSAGE (I1, I2)

                    [NONE]    Outputs the MPE error message I2 in message set
                              I1.  CIERRs are in message set 2, FSERRs are in
                              message set 8.  E.g.  WRITEMPEMESSAGE(2,980)
                              writes "COMMAND GREATER THAN 278 CHARACTERS LONG.
                              (CIERR 980)" to your terminal;
                              WRITEMPEMESSAGE(8,52) would write "NONEXISTENT
                              PERMANENT FILE  (FSERR 52)".


WRITEMPEXLSTATUS_1187
WRITEMPEXLSTATUS

WRITEMPEXLSTATUS (I)

                    [NONE]    Outputs the message corresponding to the MPE/iX
                              intrinsic status code passed as I.


INPUT_1188
INPUT

INPUT ([S][,I])     [STR]     Prompts the user with string S (optional), then
                              waits I seconds (optional, default forever) for a
                              response.  Returns the response as a string.  If
                              the user does not respond before the timeout, ""
                              (the null string) is returned and a warning is
                              issued.


PRINTOPREPLY_1189
PRINTOPREPLY

PRINTOPREPLY (S)    [STR]     Sends the string S as a message to the system
                              console and waits for the operator to :REPLY.
                              Returns the value given by the operator in the
                              :REPLY command.


SONALIVE_1190
SONALIVE

SONALIVE (I)        [BOOL]    Returns TRUE if the process whose PIN is I is
                              alive and a son process of MPEX.  Useful for
                              checking on the progress of son processes that
                              you've started (whose PINs you got from the
                              MPEXPIN JCW).


SONALIVENAME_1191
SONALIVENAME

SONALIVENAME (I,S)  [BOOL]    Returns TRUE if the process whose PIN is I is
                              alive, is a son process of MPEX, and is running
                              the program S.

ISCHLOGONED()       [BOOL]    Returns TRUE if session has done a CHLOGON to
                              another logon (and hasn't switched back yet).


BOUND_1192
BOUND

BOUND (varname)     [BOOL]    True if the variable varname exists.  e.g.
                              BOUND(MYVAR) returns true if the variable "MYVAR"
                              exists.  Note: do not put quotes around the
                              variable name.


TYPEOF_1193
TYPEOF

TYPEOF (expression) [INT]     Returns the MPE type of an expression or or
                              variable, or returns an error if the expression
                              is invalid.  This function returns:

                                   1 if expression evaluates to an INTEGER

                                   2 if expression evaluates to a STRING

                                   3 if expression evaluates to a BOOLEAN

                                 101 if expression evaluates to a REAL number

                                 102 if expression evaluates to a DATE

                                 103 if expression evaluates to a TIME

                              Note: when MPEX expressions of type DATE, TIME
                              and REAL, are assigned to a variable, the
                              variable will be of type STRING.


SVAR_1194
SVAR

SVAR (S)            [STR]     Retrieves the value of an MPE variable (either
                              predefined [see below], set by the MPEX %SETVAR
                              command, or a JCW) as a string; if the variable
                              is not a string variable, formats it as a string.
                              If the variable does not exist, returns an empty
                              string.  For instance, SVAR("HPACCOUNT") returns
                              the value of the predefined HPACCOUNT variable --
                              the logon account.

SVAR (S1,S2)        [STR]     Same as SVAR(S), but returns the string S2 if the
                              variable S1 doesn't exist.


IVAR_1195
IVAR

IVAR (S)            [INT]     Retrieves the value of an MPE variable as an
                              integer; if the variable is a string or does not
                              exist, returns 0.

IVAR (S,I)          [INT]     Same as IVAR(S), but returns the integer I if the
                              variable is a string or doesn't exist.


BVAR_1196
BVAR

BVAR (S)            [BOOL]    Retrieves the value of an MPE variable as a
                              boolean.  If the variable does not exist, returns
                              FALSE.

BVAR (S,B)          [BOOL]    Same as BVAR(S), but returns the value B if the
                              variable doesn't exist.


SVARSET_1197
SVARSET

SVARSET (S1,S2)     [STR]     Sets the variable S1 to the string value S2.


IVARSET_1198
IVARSET

IVARSET (S,I)       [INT]     Sets the variable S to the integer value I.


BVARSET_1199
BVARSET

BVARSET (S,B)       [BOOL]    Sets the variable S to the boolean value B.


SETVAR_1200
SETVAR

SETVAR (varname, expression)

                    [???]     Sets the variable "varname" to the value of
                              "expression".  Returns the value of "expression".
                              The type depends on the type of "expression"
                              (integer, string, or boolean).
                              SETVAR(TESTVAR,"TESTVALUE") returns "TESTVALUE"
                              and sets the variable TESTVAR to "TESTVALUE".


CMDPARM_1201
CMDPARM

CMDPARM (S)         [STR]     Returns the value of the parameter indicated by S
                              of the currently-executing command file or UDC.
                              Why use CMDPARM("XYZ") and not "!XYZ"? Because
                              CMDPARM works even when the parameter XYZ
                              contains embedded quotes -- the "!XYZ" syntax
                              would cause a syntax error in this case.


RANDOMNAME_1202
RANDOMNAME

RANDOMNAME          [STR]     Returns a string of 8 random alphabetic
                              characters, useful for setting random passwords
                              and lockwords.  The letters are alternating
                              consonants and vowels (for ease of pronouncing
                              and remembering).  There are over 100 million
                              possible values of this function.


PAUSE_1203
PAUSE

PAUSE (I)           [NONE]    Pauses for I seconds.  Returns no result;
                              therefore, it can only be used in a %CALC
                              PAUSE(I) or in an "expression program".


ACCTEXISTS_1204
ACCTEXISTS

ACCTEXISTS (S)      [BOOL]    TRUE if account indicated by the string S exists.
                              E.g.  ACCTEXISTS("SYS") is TRUE.


USEREXISTS_1205
USEREXISTS

USEREXISTS (S)      [BOOL]    TRUE if the user.account indicated by the string
                              S exists.  E.g.  USEREXISTS("MANAGER.SYS") is
                              TRUE.


GROUPEXISTS_1206
GROUPEXISTS

GROUPEXISTS (S)     [BOOL]    TRUE if the group.account indicated by the string
                              S exists.  E.g.  GROUPEXISTS("PUB.SYS") is TRUE.


VEACCTINFO_1207
VEACCTINFO

VEACCTINFO (S).attrvar [???]  Returns the MPE account attribute variable
                              indicated by "attrvar" for the account indicated
                              by S.  "Attrvar" must be one of the account
                              attribute variables discussed in the "Object
                              Attribute Variables" chapter of the
                              VEAUDIT User Manual.


VEUSERINFO_1208
VEUSERINFO

VEUSERINFO (S).attrvar [???]  Returns the MPE user attribute variable indicated
                              by "attrvar" for the user.account indicated by S.
                              "Attrvar" must be one of the user attribute
                              variables discussed in the "Object Attribute
                              Variables" chapter of the VEAUDIT User Manual.


VEGROUPINFO_1209
VEGROUPINFO

VEGROUPINFO (S).attrvar [???] Returns the MPE group attribute variable
                              indicated by "attrvar" for the group.account
                              indicated by S.  "Attrvar" must be one of the
                              group attribute variables discussed in the
                              "Object Attribute Variables" chapter of the
                              VEAUDIT User Manual.


VEJOBINFO_1210
VEJOBINFO

VEJOBINFO (jobtype,jobnum).attrvar

                    [???]     Returns the job attribute variable indicated by
                              "attrvar" for the given job.  "Jobtype" is a
                              string, and must be either "J" or "S"; "jobnum"
                              must be an integer expression.  "Attrvar" must be
                              one of the job/session attribute variables
                              discussed in the "Job/Session Attributes" chapter
                              of the MPEX User Manual.

VEJOBINFO (jobid).attrvar[???]Same as above, but "jobid" is a string of the
                              format '#J999' or '#S999'.


JSCOUNT_1211
JSCOUNT

JSCOUNT (S)         [INT]     Counts the number of jobs or sessions that match
                              the userset given by the string S; for instance,
                              JSCOUNT("@.AP-MGR.AP&ONLINE") returns the number
                              of sessions ("&ONLINE") that are logged on to the
                              AP account ("@.AP") but not as MGR.AP
                              ("-MGR.AP").  Note that the evaluation of +, -,
                              and & proceeds from left to right (unless you use
                              parentheses to override this).

                              "Usersets" are discussed in more detail in the
                              SECURITY User Manual.


Terminal_manipulation_functions__1212
Terminal manipulation functions

The following functions make it easier for you to do special HP
terminal-dependent things (e.g.  position the cursor, clear the screen, etc.)
-- useful in command files, SECURITY menus, etc.:


HPTERMINAL_1213
HPTERMINAL

HPTERMINAL ()       [BOOL]    Returns TRUE if the terminal is configured as an
                              HP terminal (terminal type 10), FALSE if it
                              isn't.  Note that this function must be called as
                              HPTERMINAL() -- you can not omit the "()".


TERMPOS_1214
TERMPOS

TERMPOS (I1,I2)     [STR]     Returns the escape sequence that causes an HP
                              terminal to position its cursor at  row I1,
                              column I2 (counting from 0).


TERMCLEAR_1215
TERMCLEAR

TERMCLEAR ()        [STR]     Returns the escape sequence that causes an HP
                              terminal to clear the rest of the screen from the
                              cursor to the end of memory.  To clear the entire
                              screen, you should output
                              TERMPOS(0,0)+TERMCLEAR().  Note that this
                              function must be called as TERMCLEAR() -- you can
                              not omit the "()".


TERMFKEY_1216
TERMFKEY

TERMFKEY (I)        [STR]     Returns the string that corresponds to hitting
                              the function key numbered I on an HP terminal.
                              Useful for checking to see if a user hit a
                              particular function key, e.g.  IF
                              USERINPUT=TERMFKEY(8) THEN ...  I must be between
                              1 and 8.


TERMFKEYNUMBER_1217
TERMFKEYNUMBER

TERMFKEYNUMBER (S)  [INT]     If S is the string that is sent by an HP terminal
                              when a function key is hit, returns the number (1
                              through 8) of that function key; if it isn't,
                              returns 0.  Useful for checking to see if a user
                              hit a function key, and if so, which one.


SECURITY_related_functions__1218
SECURITY-related functions

The following functions let you do special SECURITY-related things:


VEPROFILEEXISTS_1219
VEPROFILEEXISTS

VEPROFILEEXISTS (S) [BOOL]    TRUE if SECURITY/3000 user profile for the
                              session,user.account indicated by the string S
                              exists; e.g.  VEPROFILEEXISTS("NIVEN,WRITER.SF").


VEPROFILEINFO_1220
VEPROFILEINFO

VEPROFILEINFO (S).attrvar

                    [???]     Returns the SECURITY/3000 user profile attribute
                              variable indicated by "attrvar" for the
                              session,user.account indicated by S.  "Attrvar"
                              must be one of the user profile attribute
                              variables discussed in the "Listing User
                              Profiles" chapter of the SECURITY User Manual.
                              For example, VEPROFILEINFO("LN,WRITER.SF").NAME
                              might be the string "Larry Niven").


SECURITYLOG_1221
SECURITYLOG

SECURITYLOG (S)     [NONE]    Writes a record containing the given string to
                              the SECURITY log file.  This record will then
                              show up (with type "Manual") in the SECURITY
                              LISTLOG entry point output, or can be specially
                              looked for using the OPMANUAL and QUALIFIER
                              selection conditions.  Returns no result;
                              therefore, it can only be used in a %CALC
                              SECURITYLOG(...) or in an "expression program".


BADPASSWORD_1222
BADPASSWORD

BADPASSWORD (S)     [BOOL]    Returns TRUE if the string S is one of the "bad
                              passwords" indicated in the
                              BADPASS.AUDITDAT.VESOFT file as too easy to guess
                              (see the VEAUDIT User Manual), and prints the
                              associated error message; otherwise returns
                              FALSE.


File_attribute_functions__1223
File attribute functions

These functions let you do some pretty interesting things to files.  Don't let
their position near the end of the list fool you -- these are some of the most
useful expressions we provide.

Note: MPEX's FINFO, VEFINFO, and FEXISTS functions normally return information
about permanent files; MPE/iX's FINFO function, however, first looks for the
file as a temporary file and only then looks at the permanent file.  By doing a


MPEXFINFOANY_1224
MPEXFINFOANY
   :SETJCW MPEXFINFOANY=1

you can make MPEX's FINFO, VEFINFO, and FEXISTS functions behave like MPE/iX's
FINFO; i.e.  they will look first for a temporary file and then (if no
temporary file with the given name exists) for a permanent file.


FREMLOCKWORD_1225
FREMLOCKWORD

FREMLOCKWORD(S)     [STR]     Takes a string S that contains a filename and
                              returns the same filename, fully qualified but
                              WITHOUT a lockword (if any).


OBJECTFILE_1226
OBJECTFILE

OBJECTFILE(S)       [STR]     (Only usable within MPEX's %REPEAT...%FORFILES
                              construct, documented in the MPEX User Manual.)
                              Returns the name of a file in the "object
                              fileset" indicated by S that corresponds to the
                              current file in the "source fileset".  For
                              example, if the "source fileset" is S@.DATA and
                              the current filename is SMYPROG.DATA, then
                              OBJECTFILE("B@.BACKUP") is "BMYPROG.BACKUP".


FEXISTS_1227
FEXISTS

FEXISTS (S)         [BOOL]    Checks to see if the permanent file indicated by
                              S exists -- if it does, returns TRUE; if it
                              doesn't, FALSE.


FTEMPEXISTS_1228
FTEMPEXISTS

FTEMPEXISTS (S)     [BOOL]    Just like FEXISTS, but for temp files.


FPERMEXISTS_1229
FPERMEXISTS

FPERMEXISTS (S)     [BOOL]    Just like FEXISTS; use this function if you
                              SETJCW MPEXFINFOANY=1 and you want to only check
                              for a permanent file.


FANYEXISTS_1230
FANYEXISTS

FANYEXISTS (S)      [BOOL]    True if either a permanent or a temp file with
                              the given name exists.


VEFINFO_1231
VEFINFO

VEFINFO (S).fieldname [???]   Finds the permanent file S and returns an
                              arbitrary piece of information about the file
                              indicated by "fieldname".  "Fieldname" must be
                              one of the file attribute variables discussed in
                              "File Attribute Variables And Functions" in the
                              MPEX Filesets chapter of the MPEX User Manual.
                              For example:

VEFINFO("AP010S.DATA").CODE         returns AP010S.DATA's filecode as a string

VEFINFO("XX1.PUB").SECTORS          returns the number of sectors used by
                              XX1.PUB;

VEFINFO(DBSETNAME+".DB").DBSETNAME  returns the IMAGE dataset name of the
                              dataset whose file name is in the DBSETNAME
                              variable in the DB group.


VEFTEMPINFO_1232
VEFTEMPINFO

VEFTEMPINFO (S).fieldname

                    [???]     Just like VEFINFO, but for temp files.


VEFPERMINFO_1233
VEFPERMINFO

VEFPERMINFO (S).fieldname

                    [???]     Just like VEFINFO; use this function if you
                              SETJCW MPEXFINFOANY=1 and you want to only check
                              for a permanent file.


VEFANYINFO_1234
VEFANYINFO

VEFANYINFO (S).fieldname

                    [???]     Just like VEFINFO, but check first for a temp
                              file, then a permanent file.


FINFO_1235
FINFO

FINFO (S,I)         [???]     The FINFO function allows you to extract various
                              pieces of information about a (by default,
                              permanent) file named by S.  The information you
                              get -- and its type -- depends on the value of
                              the second parameter (I), which must be an
                              integer constant.  Note that all string results
                              have trailing blanks stripped.  If the file
                              doesn't exist, an error is reported.


FTEMPINFO_1236
FTEMPINFO

FTEMPINFO (S,I)     [???]     Just like FINFO, but only looks at temp files.


FPERMINFO_1237
FPERMINFO

FPERMINFO (S,I)     [???]     Just like FINFO, but only looks at permanent
                              files.


FANYINFO_1238
FANYINFO

FANYINFO (S,I)      [???]     Just like FINFO, but looks first for a temp file,
                              and then (if it doesn't find one), for a
                              permanent file.

Although MPE/iX's FINFO function looks first for a temp file and then, if it
doesn't find one, for a perm file, the MPEX FINFO function only looks for a
perm file.  As discussed above, you can set the JCW MPEXFINFOANY to 1 to make
FINFO work the same way in MPEX that it does in MPE/iX.


List_of_MPE_FINFO_parameters_1239
List of MPE FINFO parameters
Both MPE/iX and MPEX now allow a string to be supplied as the second parameter
of the FINFO function, instead of the hard-to-remember numeric parameter
originally supported.  As the list of supported string attributes is poorly
documented by HP, we include the complete list here:

EXISTS                    =  0         DEVNAME                   = 23
FULL FILENAME             =  1         FMTMODTIME                = 24
FULLFNAME                 =  1         LAST MOD TIME             = 24
FULLY QUALIFIED FILENAME  =  1         INTMODTIME                =-24
FILENAME ONLY             = -1         LAST MOD TIME INTEGER     =-24
FNAME                     = -1         FIRST USER LABEL          = 25
GROUP NAME                =  2         UFID                      = 27
GROUP                     =  2         UNIQUE FILE ID            = 27
ACCOUNT NAME              =  3         BYTE FILE LIMIT           = 28
ACCOUNT                   =  3         BYTELIMIT                 = 28
ACCT                      =  3         BYTE DATA OFFSET          = 29
CREATOR                   =  4         DATASTART                 = 29
FMTSECURITY               =  5         BYTE RECORD SIZE          = 30
FORMATTED SECURITY MATRIX =  5         BYTERECSIZE               = 30
INTSECURITY               = -5         BYTE BLOCK SIZE           = 31
SECURITY MATRIX           = -5         BYTEBLKSIZE               = 31
CREATED                   =  6         BYTE EXTENT SIZE          = 32
CREATION DATE             =  6         BYTEEXTSIZE               = 32
FMTCREATED                =  6         LOCKWORD                  = 33
CREATION DATE INTEGER     = -6         VOLRESTR                  = 34
INTCREATED                = -6         VOLUME RESTRICTION        = 34
ACCESSED                  =  7
FMTACCESSED               =  7      The following attributes are only
LAST ACCESS DATE          =  7      available on POSIX systems:
INTACCESSED               = -7         VOLUME SET NAME           = 35
LAST ACCESS DATE INTEGER  = -7         LOG SET ID                = 36
FMTMODDATE                =  8         LOGICAL DEVICE NUMBER     = 37
LAST MOD DATE             =  8         LDEV                      = 37
MODIFIED                  =  8         POSIXFULLFNAME            = 38
INTMODDATE                = -8         POSIX FULL FILENAME       = 38
LAST MOD DATE INTEGER     = -8         NUM HARD LINKS            = 39
FILE CODE MNEMONIC        =  9         NUMHARDLINKS              = 39
FMTFCODE                  =  9         LAST ACCESS TIME          = 40
FCODE                     = -9         ACCESS TIME               = 40
FILE CODE                 = -9         FMTACCESSTIME             = 40
INTFCODE                  = -9         LAST ACCESS TIME INTEGER  =-40
USER LABELS WRITTEN       = 10         INTACCESSTIME             =-40
USER LABELS AVAIL         = 11         STATUS CHANGE TIME        = 41
FILE LIMIT                = 12         FMTSTATUSCHANGETIME       = 41
LIMIT                     = 12         INTSTATUSCHANGETIME       =-41
FMTFOPT                   = 13         STATUS CHANGE DATE        = 42
FORMATTED FOPTIONS        = 13         CHANGE DATE INTEGER       =-42
FOPTIONS                  =-13         OWNER                     = 43
INTFOPT                   =-13         FILE OWNER NAME           = 43
RECORD SIZE               = 14         UID                       = 44
RECSIZE                   = 14         FILE OWNER ID             = 44
BLOCK SIZE                = 15         FILEGROUP                 = 45
BLKSIZE                   = 15         FILE GROUP NAME           = 45
MAX EXTENTS               = 16         GID                       = 46
MAXEXT                    = 16         FILE GROUP ID             = 46
LAST EXTENT SIZE          = 17         FILETYPE                  = 47
LASTEXTSIZE               = 17         FILE TYPE                 = 47
EXTENT SIZE               = 18         FILE TYPE INTEGER         =-47
EXTSIZE                   = 18         INTFILETYPE               =-47
END OF FILE               = 19         RECTYPE                   = 48
EOF                       = 19         RECORD TYPE               = 48
ALLOC TIME                = 20         BYTEFILESIZE              = 49
FMTALLOCTIME              = 20         BYTE FILE SIZE            = 49
ALLOC TIME INTEGER        =-20         KSAM VERSION              = 50
INTALLOCTIME              =-20         KSAMVERS                  = 50
ALLOC DATE                = 21         KSAMPARAM                 = 51
ALLOCATED                 = 21         KSAM LABEL                = 51
FMTALLOCDATE              = 21         DEVTYPE                   = 52
ALLOC DATE INTEGER        =-21         DEVICE TYPE               = 52
INTALLOCDATE              =-21         DEVICE TYPE INTEGER       =-52
NUM OPEN CLOSE RECS       = 22         INTDEVTYPE                =-52
DEVICE NAME               = 23         RELEASED                  = 53

Note that many of these entries are synonyms, and that negative numeric
parameters return the same information as corresponding positive ones, but
unformatted.


File_I_O_functions__1240
File I/O functions

With these functions, you can access (open, read, write, close, etc.) disc
files, including KSAM files and IMAGE databases (see below), from within MPEX,
STREAMX, VEMENU, SECURITY's $FORBID, etc.  -- anywhere that you can use the
expression handler.  (In MPEX, you'll probably use them from the %SETVAR, %CALC
and perhaps %WHILE and %IF commands.) Collectively, these routines are referred
to as "VEFxxx functions" in our documentation.


VEFxxx_functions_1241
VEFxxx functions
It is important to note that SM users may use these functions to open, read,
and modify PRIV files.  In order to open a PRIV file, the file parameter of the
VEFOPEN and VEFREAD functions must include the correct file code.  For
instance, to open the ROOT file of a database directly, you would use:

   SETVAR ROOTFILE VEFOPEN('MYDB,OLD;CODE=-400');

WARNING: PRIV files are privileged for a reason! Writing to PRIV files, such as
IMAGE DATABASE files, may corrupt the internal structure of the file and make
it useless to your application.  Use this feature with care -- VESOFT, Inc.
cannot repair files corrupted (whether PRIVileged or not) by misuse of these
functions.

These functions roughly correspond to the file system intrinsics (see HP's  MPE
INTRINSICS REFERENCE MANUAL for details), but are often more powerful and
easier to use.  The functions are:


VEFOPEN_1242
VEFOPEN

VEFOPEN ('filename,domain;fileeqparms')

Returns an integer file number to be used by the other functions.  The string
you pass to VEFOPEN should look very much like a :FILE equation (without the
word "FILE"), e.g.  VEFOPEN('MYFILE,OLD;ACC=INOUT;SHR').  However, several new
parameters are supported:

    ;OLDANY     -- try to open this as a temporary file, and if that fails, as
                   a permanent one.
    ;NOFILEEQ   -- ignore :FILE equations.
    ;ULABEL=num -- create the new file with room for up to <num> user labels.
    ;BUILD      -- build the file first, and then re-open it.
    ;MAYBUILD   -- if the file already exists, simply open it; if it doesn't
                   exist, build it first.
             Note: you must specify ",OLD" when using ";MAYBUILD"!


VEFCLOSE_1243
VEFCLOSE

VEFCLOSE (fnum[,disposition])

Closes the given file number.  "Disposition" should be a string, and may
contain the following keywords delimited by semicolons (e.g.  "SAVE;SQUEEZE"):

    SAVE         -- save file as permanent.
    TEMP         -- save file as temporary.
    DEL          -- purge file.
    SQUEEZE      -- set file limit to be equal to EOF.
    XLTRIM       -- return to free space any unused space beyond EOF (MPE/iX
                    only).
    CREATORONLY  -- save file with access mask set to allow access only to its
                    creator.

If the DISPOSITION string is omitted, the file will be closed without any of
the above parameters (which means leave the file as it is, just like FCLOSE
disposition 0).


VEFREAD_1244
VEFREAD


VEEOF_1245
VEEOF

VEFREAD (FNUM)      [STR]     Reads the next record from the file; sets VEEOF
                              to TRUE if read encounters end-of-file.


VEFREADV_1246
VEFREADV


VEEOF_1247
VEEOF

VEFREADV (S,FNUM)   [BOOL]    Reads the next record from the file and puts it
                              into the variable given by S; returns TRUE if all
                              OK, FALSE if EOF (also sets VEEOF to TRUE if read
                              encounters end-of-file).  Example: WHILE
                              VEFREADV("REC",MYFNUM) DO ...  loops through the
                              records in MYFNUM, putting each one in turn into
                              the variable REC.


VEFREADDIR_1248
VEFREADDIR

VEFREADDIR (FNUM,I) [STR]     Reads record I from the file.  May only be used
                              with fixed record-length files.


VEFREADLABEL_1249
VEFREADLABEL

VEFREADLABEL (FNUM,I)

                    [STR]     Reads label I from the file.


VEFWRITE_1250
VEFWRITE

VEFWRITE (FNUM,S[,I])[NONE]   Writes S to the file, optionally with carriage
                              control I.


VEFWRITEDIR_1251
VEFWRITEDIR

VEFWRITEDIR (FNUM,S,I)

                    [NONE]    Writes S as record I to the file.


VEFWRITELABEL_1252
VEFWRITELABEL

VEFWRITELABEL (FNUM,S,I)

                    [NONE]    Writes S as label I to the file.


VEFPOINT_1253
VEFPOINT

VEFPOINT (FNUM,I)   [NONE]    Points the file to record I.


VEFCONTROL_1254
VEFCONTROL

VEFCONTROL (FNUM,I,J)

                    [INT]     Does an FCONTROL mode I with parameter J.
                              Returns the value returned by FCONTROL's third
                              parameter.


VEFLOCK_1255
VEFLOCK

VEFLOCK (FNUM,L)    [NONE]    Locks the file; if L=TRUE and file already locked
                              by someone else, waits; if L=FALSE, doesn't wait.


VEFUNLOCK_1256
VEFUNLOCK

VEFUNLOCK (FNUM)    [NONE]    Unlocks the file.


VEFINFO_1257
VEFINFO

VEFINFO (FNUM).xxx  [NONE]    Returns information about the file -- just like a
                              normal VEFINFO, but of an open file.


VEPRINTFILEFINFO_1258
VEPRINTFILEFINFO

VEPRINTFILEINFO (FNUM)

                    [NONE]    Prints a "tombstone" containing various
                              information about the file.


VEFREADBYKEY_1259
VEFREADBYKEY


VEEOF_1260
VEEOF

VEFREADBYKEY (FNUM,S,I)

                    [STR]     Reads a KSAM file record with key S (key start
                              position given as I); sets VEEOF to TRUE if the
                              record was not found.


VEFREADBYKEYV_1261
VEFREADBYKEYV

VEFREADBYKEYV (S1,FNUM,S2,I)

                    [BOOL]    Analogous to VEFREADV.


VEFFINDBYKEY_1262
VEFFINDBYKEY


VEEOF_1263
VEEOF

VEFFINDBYKEY (FNUM,S,I,S1)

                    [BOOL]    Finds a KSAM file record with key equal to S (if
                              S1 is "="), greater than S (if S1 is ">"), or
                              greater than or equal to S (if S1 is ">=").  Key
                              start position given as I; partial key lookup is
                              supported (if S is shorter than the key length).
                              This function returns TRUE if found or FALSE if
                              not found, and sets the VEEOF variable to the
                              opposite setting (i.e., FALSE if found and TRUE
                              if not found).


VEFREMOVE_1264
VEFREMOVE

VEFREMOVE (FNUM)    [STR]     Removes the current record in the KSAM file.


VEFUPDATE_1265
VEFUPDATE

VEFUPDATE (FNUM,S)  [STR]     Replaces the current record in the KSAM file by
                              S.


VEFFINDN_1266
VEFFINDN

VEFFINDN (FNUM,I,J) [STR]     Finds record number I (key start position given
                              as J).


VEFREADC_1267
VEFREADC


VEEOF_1268
VEEOF

VEFREADC (FNUM)     [STR]     Reads the chronologically next record.


VEFREADCV_1269
VEFREADCV


VEEOF_1270
VEEOF

VEFREADCV (S,FNUM)  [BOOL]    Analogous to VEFREADV.


VEEOF_1271
VEEOF
   * If there is any error accessing the file, the command will abort with
     CIERROR set to 30080 and FSERROR set to the file system error number; you
     can, of course, use %CONTINUE, %IF, %TRAPERROR, etc.  to do appropriate
     error handling.  The only exception to this are an end of file discovered
     by VEFREAD or VEFREADC (not by any of the other VEFREADxxx functions), or
     a nonexistent key discovered by VEFREADBYKEY or VEFFINDBYKEY; these will
     cause no error, but rather return an empty string, and set the special
     VEEOF variable to TRUE.  The alternate VEFREADV, VEFREADCV, and
     VEFREADBYKEYV functions return the eof/no key condition as their result,
     and put the record that was read into a variable whose name is passed to
     them.


VEFSERR_1272
VEFSERR
   * If any of the file I/O functions encounter a file system error, the
     variable VEFSERR is set to the MPE FSERROR number.

   * The VEFREADxxx and VEFWRITExxx functions can be passed a
     filename/file-parameter string (like the one that you can pass to VEFOPEN)
     as the first parameter, instead of the file number.  We will then open the
     file, do the operation, and immediately close the file; thus, VEFREADDIR
     ('MYFILE,OLD', 5) will return record 5 of the file MYFILE.  Note that it
     is important that you specify ,OLD, ;ACC=OUTKEEP (for VEFWRITExxx calls),
     and whatever other parameters you need to make the I/O work properly.

   * The VEFREADxxxV functions return the record that is read into an MPEX (or
     MPE/iX) variable, not an expression program variable created by the VAR
     statement in an expression program (see "Advanced Expression Programming"
     below).

   * What if the file you're reading or writing contains binary (rather than
     ASCII) data? You can extract this data from the record by using the new
     INTEGER function, e.g.  INTEGER(REC[10:2]) to extract the 2-byte integer
     starting with byte 10 (counting from 0) of REC; you can assemble a record
     from ASCII and binary data by using the 'I2' and 'I4' format specifiers of
     STRWRITE, e.g.  VEFWRITE (MYFNUM, STRWRITE(NAME:30, NUMKIDS:'I2',
     SSN:'I4')).  For more documentation on INTEGER, 'I2', and 'I4', see
     "Output Formatting" below.

This facility has certain limitations that you should be aware of.  Some of
them may be removed in the future, but we aren't making any promises.

   * These functions are probably not fast enough to do serious processing of
     large files.  Actually, it's not so much the functions that are slow as
     the MPEX commands -- like %CALC and %SETVAR -- in which you'll use the
     functions.  If you want to process a few records of a very large file, you
     might want to find them first using the comparatively fast %PRINT
     ;SEARCH=, send its output to a temporary file, and then process the file
     with the VEFxxx functions.

   * Because string variables can be at most 255 characters long, you'll have
     trouble processing files with records longer than 255 characters.

   * VEFINFO currently works only on disc, non-remote files.

Here is an example making use of some of these functions.  It uses a file named
STRLIST, which is a list of strings to search for, and reports all the files in
a fileset that contain ANY of those strings.

   PARM CS$FILESET
   REPEAT
   SETVAR FNUM VEFOPEN("STRLIST,OLD")
   TRAPERROR
   WHILE VEFREADV("CURREC",FNUM) DO
      SETVAR SEARCHSTR TOKEN(CURREC," ")
      IF RFILE.FSEARCHSTRING(SEARCHSTR)>0 THEN
         ECHO !MPEXCURRENTFILE contains the string !SEARCHSTR
      ENDIF
   ENDWHILE
   CLEANUP
      CALC VEFCLOSE(FNUM)
      DELETEVAR CURREC
      DELETEVAR FNUM
   ENDCLEANUP
   FORFILES !FILESET


Database_I_O_functions__1273
Database I/O functions

These functions provide access to IMAGE databases, and are similar to the File
I/O functions above.  Please don't throw away your applications now that you
have these functions.  You won't get incredibly fast performance from them, but
if you only need to affect an entry or two, they can be extremely convenient!

OPENING A DATABASE FOR ACCESS


Opening_a_database_for_access_1274
Opening a database for access

Note that in the function definitions shown below, dbid can be either the
string returned by VEDBOPEN, or a string containing 'dbname,pass,mode' (in the
latter case, the open and close will be done automatically).  dset is a string
containing the name of of the dataset being accessed.  list is a string
containing an ordered list of data item names (delimited by commas), or '@' to
indicate all items.  buffer is a string containing the data item values
specified in the list parameter (and in the same order).

If you are doing a single operation, such as adding a new record to a detail
set, you should use the automatic method of opening, locking, and closing a
database.  To do this, simply specify the name of the database, the password,
and the mode to open the database as a string constant or variable in the call
to VEDBPUT.  If you intend to perform a number of operations, such as finding a
detail record, updating a few fields, then re-writing the detail record, it may
be better to use the VEDBOPEN function to keep the database open between VEDB
calls.

In either case, these functions will look for and evaluate a database Access
Control File if one exists.  NOTE that if VEDBOPEN is being called from a
COMMAND file, MAIN.PUB.VESOFT should be specified in a $PROGRAM clause.
However, if VEDBOPEN is being called from an EXPRESSION PROGRAM, the name of
the EXPRESSION PROGRAM should be specified in a $PROGRAM clause.

DETERMINING THE STATUS OF A VEDB CALL


Determining_the_status_of_a_VEDB_call_1275
Determining the status of a VEDB call


VEDBERR_1276
VEDBERR
All functions (except for VEDBOPEN and VEDBGET) return TRUE if all went well,
FALSE if there was an error (EOF, BOF, end of chain, beginning of chain, no
such key, duplicate key, etc.) and abort in case of some other error.  The
predefined variable VEDBERR will be set to word 0 of the status array after
each call to a VEDBxxx function and can be tested for the exact error.  We also
display the DBERROR message in case of an error.

In addition to VEDBERR, the following predefined variables can be used (where
appropriate, depending upon which VEDBxxx function was called) to retrieve
information that is returned in the STATUS array.


VEDBDATALEN_1277
VEDBDATALEN


VEDBRECNUM_1278
VEDBRECNUM


VEDBCHAINLEN_1279
VEDBCHAINLEN


VEDBPREVREC_1280
VEDBPREVREC


VEDBNEXTREC_1281
VEDBNEXTREC
   Variable     Status
     name       Word

 VEDBDATALEN      1
 VEDBRECNUM       1
 VEDBCHAINLEN     2
 VEDBPREVREC      3
 VEDBNEXTREC      4

Please consult your HP TurboIMAGE Reference Manual for details about each of
these status array elements as well as the corresponding IMAGE intrinsics for
the following VEDBxxx functions.


VEDBOPEN_1282
VEDBOPEN

VEDBOPEN ('dbname, pass, mode')   [STR]

          DBOPEN.  Accepts a string containing the database name, password, and
          mode (delimited by commas) and returns a string value that can then
          be used as the dbid in the other VEDBxxx functions.  Remember to
          close the base using VEDBCLOSE.


VEDBFIND_1283
VEDBFIND

VEDBFIND (dbid, dset, [mode,] item, key) [BOOL]

          DBFIND.  Sets up pointers to the first and last entries of a detail
          chain to prepare for subsequent VEDBGETs.  The dset parameter must be
          the name of a DETAIL dataset.  The item is the name of the desired
          search item.  The key parameter is a string containing the value of
          the search item in the desired chain.  The optional MODE parameter is
          used for accessing the TPI (Third Party Interface) feature provided
          by TurboIMAGE/iX on MPE/iX 4.0 and later operating systems.


VEDBGET_1284
VEDBGET


VEEOF_1285
VEEOF

VEDBGET (dbid, dset, mode, list[, key]) [STR]

          DBGET.  Returns a string containing the items requested in the list
          parameter.  mode is an integer that determines the reading method
          (see your HP TurboIMAGE Reference Manual for details).  Optionally, a
          key value (which must be the correct length) may be specified to
          support modes 4, 7, and 8.  If you are using mode 4 and want record
          100, use STRWRITE(100:'I4') as the key value.  This function sets the
          special variable VEEOF to TRUE if the desired entry couldn't be
          found, or EOF is reached.  You can retrieve a maximum of 255
          characters with a single VEDBGET.


VEDBGETV_1286
VEDBGETV


VEEOF_1287
VEEOF

VEDBGETV ('varname', dbid, dset, mode, list[, key]) [BOOL]

          DBGET.  Same as VEDBGET except that it returns a BOOLEAN value (just
          like the other functions).  The requested item values are assigned to
          the variable specified in the first parameter.  (Also sets VEEOF TRUE
          if entry couldn't be found, or EOF is reached).  Note: IMAGE requires
          you to pass it a key of the correct length, space-filled; use
          STRWRITE(str:len) if necessary).


VEDBPUT_1288
VEDBPUT

VEDBPUT (dbid, dset, list, buffer) [BOOL]

          DBPUT.  Adds a new entry to a dataset.  If the database was opened
          with VEDBOPEN, it must have been opened in access mode 1, 3, or 4.


VEDBPUTL_1289
VEDBPUTL

VEDBPUTL (dbid, dset, list, buffer) [BOOL]

          DBPUT, auto-lock.  Same as VEDBPUT except that it automatically does
          a DBLOCK, and DBUNLOCK around the DBPUT.  This makes it more
          convenient to use the auto-open form of dbid.


VEDBUPDATE_1290
VEDBUPDATE

VEDBUPDATE (dbid, dset, list, buffer) [BOOL]

          DBUPDATE.  Modifies the values of the data items specified in list in
          the current record.  The database must be open in access mode 1, 2,
          3, or 4.


VEDBUPDATEK_1291
VEDBUPDATEK

VEDBUPDATEK (dbid, dset, list, buffer, key) [BOOL]

          DBLOCK, DBGET, DBUPDATE, DBUNLOCK.  Allows quick updating of master
          datasets by specifying the a string containing the key value.  It
          automatically does a DBLOCK, DBGET, and DBUNLOCK for you.  This makes
          it more convenient to use the auto-open form of dbid.


VEDBDELETE_1292
VEDBDELETE

VEDBDELETE (dbid, dset)           [BOOL]

          DBDELETE.  Deletes the current entry from a dataset.  The database
          must be open in access mode 1, 3, or 4.


VEDBDELETEK_1293
VEDBDELETEK

VEDBDELETEK (dbid, dset, key)     [BOOL]

          DBLOCK, DBGET, DBDELETE, DBUNLOCK.  Same as VEDBDELETE but allows the
          quick deletion of master dataset entries by specifying a string
          containing the key value.  It automatically does a DBLOCK, DBGET, and
          DBUNLOCK for you.  This makes it more convenient to use the auto-open
          form of dbid.


VEDBLOCK_1294
VEDBLOCK

VEDBLOCK (dbid, dset, mode)       [BOOL]

          DBLOCK.  Modes 1-4 are supported.  Be careful using mode 1 or mode 3;
          they could cause a deadlock.


VEDBUNLOCK_1295
VEDBUNLOCK

VEDBUNLOCK (dbid)                 [BOOL]

          DBUNLOCK.  Relinquishes the locks acquired by all previous calls to
          VEDBLOCK.


VEDBCONTROL_1296
VEDBCONTROL

VEDBCONTROL (dbid, mode)          [BOOL]

          DBCONTROL.  Allows a process accessing the database in exclusive mode
          (VEDBOPEN mode 3) to enable or disable the 'output deferred' option.
          The mode parameter is an integer that can be either 1 or 2.  1
          enables the output deferred option, 2 disables it.  See your HP
          TurboIMAGE Reference Manual for details.


VEDBCLOSE_1297
VEDBCLOSE

VEDBCLOSE (dbid, dset, mode)      [BOOL]

          DBCLOSE.  Terminates access to a database or a dataset, or
          reinitializes access to a dataset (mode 1, 2 or 3 respectively).  To
          close the database, specify an empty string (i.e.  "") for the dset
          parameter.  See your HP TurboIMAGE Reference Manual for details.

Examples:

To assign the EMP-NAME field of the entry in dataset FOO of database MYDB whose
key is EMPID to the variable EMP_NAME:

   SETVAR EMP_NAME VEDBGET ('MYDB,,5', 'FOO', 7, 'EMP-NAME', EMPID)

Here is an MPEX command file that will accept a key value as a parameter, and
then traverses the detail chain; printing out some of the fields in each detail
entry:

   PARM CODE
   SETVAR DBID VEDBOPEN('CUST.VESOFT.LIST,VESOFT,5')
   IF NOT VEDBFIND(DBID,'TECH','CODE',UPS("!CODE")) THEN
     ECHO CANNOT FIND ANY DETAIL ENTRIES FOR CODE: !CODE
   ENDIF
   WHILE VEDBGETV('REC',DBID,'TECH',5,"OPEN'DATE,QUEST'ABOUT")
     ECHO DATE: ![CDATE(DATEPARSE(REC[0:8],"YMD"),"MM/DD/YY")]&
         ABOUT: ![REC[10:50]]
   ENDWHILE
   IF NOT VEDBCLOSE(DBID,'TECH',1) THEN
     ECHO UNABLE TO CLOSE THE BASE!
   ENDIF
   DELETEVAR DBID,REC

Here is an example of a STREAMX prompt that checks if the entered code exists
as a KEY value in a master dataset:

   ::PROMPT STRING KEYVAL="Customer code"&
   :: ;CHECK=VEDBGETV('DUMMYVAR', 'CUST.VESOFT.LIST,VESOFT,5', &
   ::                 'CUST', 7, ' ', STRWRITE(UPS(KEYVAL):6)) &
   :: ;CHECKERR= 'Invalid customer code.'


Trapping_program_output__1298
Trapping program output

Say that you want to run a program (or do an MPE command) that generates a lot
of output, but only want to see some of the output (e.g.  a particular line, or
only the error messages), or want to preprocess the output before seeing it
(e.g.  extract only a particular column range).

You could, of course, execute the program or command with $STDLIST redirected
to a disc file (issuing the proper :FILE equations, if needed), do a VEFREAD of
the file, or a %PRINT ;SEARCH=, ;CONTEXT=, or ;FORMAT=, and then purge the
file.  However, this (including the inevitable fumbling with :FILE equation
parameters) is often complicated enough that people just don't bother doing it.

With MPEX, this can be done very easily, e.g.

   %PRINT (![STDLIST('RUN MYPROG')]);SEARCH="ERROR";CONTEXT=,2;&
          FORMAT=STRWRITE(R:'GARBAGE')

This does a RUN MYPROG with STDLIST= redirected to a special (uniquely named)
temporary file, prints only those lines in that file that contain "ERROR"
(;SEARCH="ERROR"), plus two lines after each (;CONTEXT=,2), with unprintable
characters replaced by dots (;FORMAT=STRWRITE(R:'GARBAGE')), and automatically
purges the temporary file.

The key to all this is the STDLIST(S) function, which executes the command
contained in the string S with $STDLIST redirected to a temporary file, and
returns a string containing all the FOPEN parameters needed to read this file,
and delete it when it's done.  This string (which is essentially a :FILE
equation without the word "FILE") can then be passed to a VEFxxx function, or
to a %PRINT (xxx) command (the parentheses around the ![STDLIST(...)] are
necessary; otherwise %PRINT would expect only a filename, not all the FOPEN
parameters).  For instance, you might say:

   %SETVAR S VEFREAD(STDLIST('SHOWTIME'))

which will set S to be the first line of a :SHOWTIME listing.

By default, the list file is built as ;REC=-508,,V,ASCII;NOCCTL;DISC=15990,32.
If you want to change one of these parameters -- for example, make the file
fixed-record length, so that you can then do a VEFREADDIR against it -- you can
specify this as a second parameter to STDLIST, e.g.

   %SETVAR REC VEFREADDIR(STDLIST('RUN MYPROG','REC=-80,,F,ASCII'),7)

Of course, if you need to get more than one record from the file, you can
VEFOPEN the file and do VEFREADs or VEFREADDIRs using the file number.
Remember, though -- when you do the VEFCLOSE, the file will get automatically
purged.

Note: the STDLIST(S) function is implemented via the ">" I/O re-direction
facility (see "Redirecting Command Input and Output" in the MPEX User Manual).
Since I/O redirection is not allowed in the CALC (and other commands), you
can't use the CALC command in the STDLIST(S) function.


Terminal_input_functions__1299
Terminal input functions

Sometimes -- usually from within command files or flexible LISTF template files
-- you might want to prompt the user for input.  There are several functions
that do this: (F is a special "format string" that is described later -- it can
be omitted unless otherwise stated below, and defaults to the empty string):


READSTRING_1300
READSTRING

READSTRING (S[,F[,I]]) [STR]  Outputs the prompt message S and inputs a string
                              (which it returns).  I is the maximum input
                              length (default 256) (F is required if I is
                              specified, but can be just an empty string, i.e.
                              "").


READINTEGER_1301
READINTEGER

READINTEGER (S[,F]) [INT]     Outputs the prompt message S and inputs an
                              integer (which it returns).


READDATE_1302
READDATE

READDATE (S[,F])    [DATE]    Outputs the prompt message S and inputs a date
                              (which it returns).


READTIME_1303
READTIME

READTIME (S[,F])    [TIME]    Outputs the prompt message S and inputs a time
                              (which it returns).


READREAL_1304
READREAL

READREAL (S[,F])    [REAL]    Outputs the prompt message S and inputs a real
                              number (which it returns).


READSELECT_1305
READSELECT

READSELECT (S,T[,F]) [STR]    Outputs the prompt message S and inputs a single
                              character, which must be one of the characters in
                              string T; returns the character input.  If
                              carriage return was hit, returns the first
                              character of T (unless the NOCR flag was
                              specified in F).  T should not be a null string
                              ("").

If, for example, you use the expression

   READINTEGER("ENTER A NUMBER? ")

you will be prompted for input until you enter a valid number:

ENTER A NUMBER? XYZZY
An integer value between -2147483648 and 2147483647 expected.  (CIERR 10010)
ENTER A NUMBER? 1.2
An integer value between -2147483648 and 2147483647 expected.  (CIERR 10010)
ENTER A NUMBER? 55

In this case, the function's result will be 55 (the number input).

The "format string" indicated as F may contain one or more format specifiers,
delimited by commas.  Valid format specifiers are:


NOECHO_1306
NOECHO

              NOECHO       don't echo the input


NOCR_1307
NOCR

              NOCR         force the user to input something, not just hit CR


RTRIM_1308
RTRIM

              RTRIM        string input: strip trailing blanks from input data


UPSHIFT_1309
UPSHIFT

              UPSHIFT      string input: upshift input data


DOWNSHIFT_1310
DOWNSHIFT

              DOWNSHIFT    string input: downshift input data


HEX_1311
HEX

              HEX          integer input: assume input is hexadecimal


OCTAL_1312
OCTAL

              OCTAL        integer input: assume input is octal


YMD_1313
YMD

              YMD          date input: assume input is [YY]YY/MM/DD (default)


MDY_1314
MDY

              MDY          date input: assume input is MM/DD/[YY]YY


DMY_1315
DMY

              DMY          date input: assume input is DD/MM/[YY]YY

Thus, saying

   READINTEGER ("SECRET NUMBER? ", "HEX,NOCR,NOECHO")

would prompt for an integer without echoing (NOECHO), assuming the input is a
hexadecimal number (HEX), and forbidding the user to just hit a CR (NOCR).

If the format string parameter is omitted, none of the options above will be
enabled (except for date input, for which YY/MM/DD input will be selected).


Terminal_input_functions__VEMODIFY_1316
Terminal input functions: VEMODIFY

In addition to prompting for strings, integers, and other data, we provide an
expression function that allows you to modify strings using the same EDITOR/MPE
modification commands or our Visual Modify keystrokes.  The VEMODIFY(...)
function takes a string as a parameter, displays the string and allows the user
to modify it, then returns the modified string to your expression program or
string variable.  By default, normal MPE/EDITOR modification commands are
accepted (<I>nsert, <D>elete, or <R>eplace characters), but if you have the
HPREDOVEMODIFY JCW set to 1, our standard Visual Modify will be used.  Please
refer to the MPEX help on %REDO for a description of the keystrokes that may be
used in "visual modify" mode.


Output_formatting_functions__1317
Output formatting functions

One function in particular (called STRWRITE) is a very powerful tool for
formatting a number of objects (strings, integers, dates, etc.) in a number of
different ways (left-justified, right-justified, decimal, hexadecimal, etc.).

The general format of STRWRITE is:

   STRWRITE (descriptor, descriptor, ..., descriptor)

where each descriptor is one of

   expression                          or
   expression:fieldlen                 or
   expression:formatstring             or
   expression:fieldlen:formatstring

STRWRITE returns a string which contains the formatted values of all the
specified expressions.

This is more easily shown than explained:

   STRWRITE ('DECIMAL', 123:6, ' IS OCTAL ', 123:'OCTAL',
             ' AND HEXADECIMAL ', 123:5:'HEX')

This operation returns the string

   'DECIMAL   123 IS OCTAL 173 AND HEXADECIMAL    7B'

which is a concatenation of

   'DECIMAL'+
   '   123'+                 (123 formatted in a field of length 6)
   ' IS OCTAL '+
   '173'+                    (123 formatted with format descriptor 'OCTAL')
   ' AND HEX '+
   '   7B'                   (123 formatted in a field of length 5 with
                                  format descriptor 'HEX')

An expression may be specified without any qualifiers (e.g.  'DECIMAL'), in
which case it's printed in some default format in a field of minimum length; it
may be specified with an integer field length, in which case it's printed
(left- or right-justified depending on the type) in a field of the given
length; it may be specified with a string format specifier, in which case it's
printed with appropriate formatting in a field of minimum length; or, it may be
specified with both.

STRING FORMATTING

When you do a STRWRITE of a string, you have several options:


STRWRITE_1318
STRWRITE

STRWRITE(S)                   Return the string verbatim

STRWRITE(S:I)                 Place the string left-justified in a field of I
                              characters, e.g.  STRWRITE("FOO":5) is "FOO  ".


RIGHTJUST_1319
RIGHTJUST

STRWRITE(S:I:'RIGHTJUST')     Place the string right-justified in a field of I
                              characters, e.g.  STRWRITE("FOO":5:"RIGHTJUST")
                              is "  FOO".


CENTER_1320
CENTER

STRWRITE(S:I:'CENTER')        Center the string in a field of I characters,
                              e.g.  STRWRITE("FOO":5:"CENTER") is " FOO ".


UPSHIFT_1321
UPSHIFT

STRWRITE(S:'UPSHIFT')         Return the string upshifted.


DOWNSHIFT_1322
DOWNSHIFT

STRWRITE(S:'DOWNSHIFT')       Return the string downshifted.


GARBAGE_1323
GARBAGE

STRWRITE(S:'GARBAGE')         Return the string with garbage (non-printable)
                              characters replaced by "."s.

Any of the above options may be combined, e.g.
STRWRITE('FOO':10:'CENTER,UPSHIFT,GARBAGE').

INTEGER FORMATTING

When you do a STRWRITE of an integer, you have several options:

STRWRITE (I)                  Return the string representation of the integer
                              I, e.g.  STRWRITE(10) is "10".

STRWRITE (I1:I2)              Return the string representation of I1
                              right-justified in I2-character field, e.g.
                              STRWRITE(10:5) is "   10".


LEFTJUST_1324
LEFTJUST

STRWRITE (I1:I2:'LEFTJUST')   Return the string representation of I1
                              left-justified in I2-character field, e.g.
                              STRWRITE(10:5:"LEFTJUST") is "10   ".


OCTAL_1325
OCTAL

STRWRITE (I:'OCTAL')          Returns the octal representation of I, e.g.
                              STRWRITE(123:"OCTAL") is "173".


HEX_1326
HEX

STRWRITE (I:'HEX')            Returns the hexadecimal representation of I, e.g.
                              STRWRITE(123:"HEX") is "7B".


ZEROFILL_1327
ZEROFILL

STRWRITE (I1:I2:'ZEROFILL')   Returns I1 right-justified in I2 characters with
                              leading zeros, e.g.  STRWRITE(123:5:"ZEROFILL")
                              is "00123".


UNSIGNED_1328
UNSIGNED

STRWRITE (I:'UNSIGNED')       Returns I formatted as an unsigned integer, e.g.
                              STRWRITE(-1:"UNSIGNED,HEX") is "FFFFFFFF".


I2_1329
I2

STRWRITE (I:'I2')             Returns the 2-byte representation of the
                              low-order 16-bits of the integer I.  Useful for
                              putting integer values into records to be written
                              to files using the VEFWRITExxx functions.


I4_1330
I4

STRWRITE (I:'I4')             Returns the 4-byte representation of the 32-bit
                              integer I.  Useful for putting integer values
                              into records to be written to files using the
                              VEFWRITExxx functions.

Again, any of the above options may be combined, e.g.
STRWRITE(I:10:"LEFTJUST,HEX,UNSIGNED").

DATE FORMATTING


STRWRITE_1331
STRWRITE
The format specifiers used for formatting dates and times are quite different
from those used for formatting strings and integers.  Here's an example of a
STRWRITE of a date:

   STRWRITE(TODAY:'%1W, %1M %RD, 19%0Y')

On 2/29/68, this would have returned

   THU, FEB 29, 1968

Why?

Well, the commas, the spaces, and the "19" are transferred verbatim to the
generated string.  However, certain special specifiers (largely those start
with "%") are replaced by one of several things: (Examples below assume the
date Friday, 2 January, 1903)

Specifier           Example   Meaning

%0D                 "02"      The day (of month), zero-filled, 2 characters.

%0M                 "01"      The month number, zero-filled, 2 characters.

%0Y                 "03"      The year, zero-filled, 2 characters.

%0C                 "19"      The 4-digit year's high-order 2-digits.

%4Y                 "1903"    The 4-digit year.

%RD, %RM, %RY       " 2"      Same as %0D/%0M/%0Y, but right-justified (i.e.
                              padded with blanks).

%D, %M, %Y          "2"       Same as %0D/%0M/%0Y, but not padded either with
                              blanks or with zeros.

%1M                 "JAN"     The month, 3-letter abbreviation.

%2M                 "January" The month's full name (first char UPPERCASE).

%1W                 "FRI"     The day-of-week, 3-letter abbreviation.

%2W                 "Friday"  The day-of-week's full name (first char
                              UPPERCASE).

DD                  "02"      Same as %0D.

MM                  "01"      Same as %0M.

YY                  "03"      Same as %0Y.

CC                  "19"      Same as %0C.

   (note that all the format specifiers must be UPPERCASE; for instance, "%1w"
   is invalid -- you must use "%1W".)

Some useful date formats might be:

   STRWRITE (D:'YY/MM/DD')                03/01/02
   STRWRITE (D:'MM/DD/YY')                01/02/03
   STRWRITE (D:'DD.MM.YY')                02.01.03
   STRWRITE (D:'%1W, %1M %RD, 19%0Y')      FRI, JAN  2, 1903
   STRWRITE (D:'%2W, %2M %0D, %0C%0Y')    Friday, January 02, 1903
   STRWRITE (D:'%4Y:MM:DD')               1903:01:02

TIME FORMATTING


STRWRITE_1332
STRWRITE
The time format specifiers are quite similar to the date format specifiers.
There are special format specifiers that indicate various parts of the time
that are to be included into the formatted string.  For instance,

   STRWRITE(RSTTIME:'%rh:%0m:%0s %x')

would, if RSTTIME were 7:33:05 PM, return

    7:33:05 PM

More precisely, the valid specifiers are: (these examples are based on a time
of 9:07:00 PM)

Specifier           Example   Meaning

%0h                 "09"      The hour (by 12-hour clock), zero-filled, 2
                              chars.

%024h               "21"      The hour (24-hour clock), zero-filled, 2 chars.

%0m                 "07"      The minute, zero-filled, 2 chars.

%0s                 "00"      The second, zero-filled, 2 chars.

%rh, %r24h, %rm, %rs " 9"     Same as the "%0..." format, but right-justified
                              in 2 characters (i.e.  padded with spaces)

%h, %24h, %m, %s    "9"       Same as the "%0..." format, but without leading
                              spaces or zeros.

%x                  "PM"      Either "AM" or "PM" depending on the hour.

(note that all the format specifiers must be lowercase; for instance, "%H" is
invalid -- you must use "%h".)

REAL NUMBER FORMATTING

Real number formatting is a bit different from all the other formatting
constructs.  Instead of being able to specify the field length and/or a format
specifier string, you may specify a field length and optionally another integer
indicating the number of digits to be printed after the decimal point.  Thus,

   STRWRITE(1.2)             yields "     1.20"
   STRWRITE(1.2:11)          yields "       1.20"
   STRWRITE(1.2:11:4)        yields "     1.2000"

As you see, the number after the first ":" is the field length (default 9) and
the number after the second ":" is the number of digits after the decimal point
(default 2).


Predefined_variables__1333
Predefined variables

These variables contain certain useful information about the running user and
about the state of the system.


HPACCOUNT_1334
HPACCOUNT

HPACCOUNT           [STR]     The logon account.


HPACCTCAP_1335
HPACCTCAP

HPACCTCAP           [INT]     The capabilities bit-mask of the logon account.


HPACCTCAPF_1336
HPACCTCAPF

HPACCTCAPF          [STR]     The logon account's capabilities formatted (in a
                              readable way, e.g.  "AM,IA,BA,SF,ND").


HPAUTOCONT_1337
HPAUTOCONT

HPAUTOCONT          [BOOL]    (User-writable) If set to TRUE, MPEX pretends
                              that there's a :CONTINUE before every command
                              that it executes; thus, command files and UDCs
                              won't abort due to command errors.  Default
                              FALSE.


HPCIDEPTH_1338
HPCIDEPTH

HPCIDEPTH           [INT]     Number of nested CIs.  Default 1 (Root CI).


HPCIERR_1339
HPCIERR

HPCIERR             [INT]     The most recent CI error number.  Just like the
                              JCW CIERROR, except that warnings are negative
                              numbers and errors are positive (CIERROR is
                              unsigned).


HPCIERRMSG_1340
HPCIERRMSG

HPCIERRMSG          [STR]     The CI error message corresponding to the value
                              of the CIERROR JCW (presumably the most recently
                              encountered CI error).


HPCMDNUM_1341
HPCMDNUM

HPCMDNUM            [INT]     Current command sequence number (esp.  useful for
                              REDO).


HPCONNMINS_1342
HPCONNMINS

HPCONNMINS          [INT]     The number of minutes since the running
                              job/session started.


HPCONSOLE_1343
HPCONSOLE

HPCONSOLE           [INT]     The LDEV of the system console.


HPCPUNAME_1344
HPCPUNAME

HPCPUNAME           [STR]     The CPU type of the computer, e.g.  "SERIES III",
                              "SERIES 4X", etc.


HPCPUSECS_1345
HPCPUSECS

HPCPUSECS           [INT]     The total number of CPU seconds used by MPEX.


HPDATE_1346
HPDATE

HPDATE              [INT]     Today's day of month.


HPDATEF_1347
HPDATEF

HPDATEF             [STR]     Today's date formatted, e.g.  "TUE, JAN 19,
                              1993".


HPDAY_1348
HPDAY

HPDAY               [INT]     Today's day of week (1=Sunday, 2=Monday, ...,
                              7=Saturday).


HPDTCPORTID_1349
HPDTCPORTID

HPDTCPORTID         [STR]     Your DTC port address (only valid if you logged
                              on from a DTC)


HPDUPLICATIVE_1350
HPDUPLICATIVE

HPDUPLICATIVE       [BOOL]    TRUE if the terminal is duplicative.


HPERRSTOLIST_1351
HPERRSTOLIST

HPERRSTOLIST        [BOOL]    (User-writable) If set to TRUE, all CI
                              errors/warnings will be written to $STDLIST; if
                              FALSE, they will be written to $STDERR instead
                              (MPE/iX feature, emulated on CLASSIC).  Default
                              TRUE.


HPEXECJOBS_1352
HPEXECJOBS

HPEXECJOBS          [INT]     Number of jobs and sessions currently executing.


HPFSERR_1353
HPFSERR

HPFSERR             [INT]     The file system error number of the most recent
                              CI command error that returned a separate file
                              system error message.


HPGROUP_1354
HPGROUP

HPGROUP             [STR]     The logon group.


HPHGROUP_1355
HPHGROUP

HPHGROUP            [STR]     The logon user's home group.


HPGROUPCAP_1356
HPGROUPCAP

HPGROUPCAP          [INT]     The capabilities bit-mask of the logon group.


HPGROUPCAPF_1357
HPGROUPCAPF

HPGROUPCAPF         [STR]     The logon group's capabilities formatted (in a
                              readable way, e.g.  "IA,BA").


HPHOUR_1358
HPHOUR

HPHOUR              [INT]     The current hour (0 to 23).


HPINPRI_1359
HPINPRI

HPINPRI             [INT]     The job/session input priority.


HPINTERACTIVE_1360
HPINTERACTIVE

HPINTERACTIVE       [BOOL]    TRUE if the terminal is interactive.


HPINTRODATE_1361
HPINTRODATE

HPINTRODATE         [STR]     The date the running job/session started (in
                              HPDATEF format).


HPINTROTIME_1362
HPINTROTIME

HPINTROTIME         [STR]     The time the running job/session started (in
                              HPTIMEF format).


HPJOBCOUNT_1363
HPJOBCOUNT

HPJOBCOUNT          [INT]     The number of jobs currently logged on.


HPJOBFENCE_1364
HPJOBFENCE

HPJOBFENCE          [INT]     The current system :JOBFENCE.


HPJOBLIMIT_1365
HPJOBLIMIT

HPJOBLIMIT          [INT]     The current system job limit.


HPJOBNAME_1366
HPJOBNAME

HPJOBNAME           [STR]     The logon job/session name.


HPJOBNUM_1367
HPJOBNUM

HPJOBNUM            [INT]     The job/session number.


HPJOBTYPE_1368
HPJOBTYPE

HPJOBTYPE           [STR]     "S" for a session, "J" for a job.


HPLDEVIN_1369
HPLDEVIN

HPLDEVIN            [INT]     The job/session input device number.


HPLDEVLIST_1370
HPLDEVLIST

HPLDEVLIST          [INT]     The job/session output device number.


HPLOCATTR_1371
HPLOCATTR

HPLOCATTR           [INT]     The logon user's local attribute.


HPMINUTE_1372
HPMINUTE

HPMINUTE            [INT]     The current minute (0 to 59).


HPMONTH_1373
HPMONTH

HPMONTH             [INT]     The current month number (1 to 12).


HPMSGFENCE_1374
HPMSGFENCE

HPMSGFENCE          [INT]     (User-writable) If set to 0 (default), all CI
                              errors/warnings are printed; if set to 1, only
                              errors are printed; if set to 2, neither errors
                              nor warnings are printed.


HPNCOPIES_1375
HPNCOPIES

HPNCOPIES           [INT]     The current job's number of copies.


HPOUTCLASS_1376
HPOUTCLASS

HPOUTCLASS          [STR]     The current job's output device class, e.g.
                              "LP".


HPOUTFENCE_1377
HPOUTFENCE

HPOUTFENCE          [INT]     Current OUTFENCE value.


HPRESULT_1378
HPRESULT

HPRESULT            [???]     (User-writable) Value of the most recent CALC
                              command executed


HPSCHEDJOBS_1379
HPSCHEDJOBS

HPSCHEDJOBS         [INT]     Number of jobs currently scheduled.


HPSESCOUNT_1380
HPSESCOUNT

HPSESCOUNT          [INT]     The number of sessions currently logged on.


HPSESLIMIT_1381
HPSESLIMIT

HPSESLIMIT          [INT]     The current system session limit.


HPSUSPJOBS_1382
HPSUSPJOBS

HPSUSPJOBS          [INT]     Number of jobs currently suspended.


HPSYSNAME_1383
HPSYSNAME

HPSYSNAME           [STR]     (User-writable) The name of the computer system.
                              Default "".


HPTIMEF_1384
HPTIMEF

HPTIMEF             [STR]     The current time, e.g.  " 3:45 PM".


HPUSER_1385
HPUSER

HPUSER              [STR]     The logon user name.


HPUSERCAP_1386
HPUSERCAP

HPUSERCAP           [INT]     The logon user's capabilities bit-mask.


HPUSERCAPF_1387
HPUSERCAPF

HPUSERCAPF          [STR]     The logon user's capabilities formatted (in a
                              readable format, e.g.  "SM,OP,AM,PM").


HPUSERCMDEPTH_1388
HPUSERCMDEPTH

HPUSERCMDEPTH       [INT]     number of nested UDCs and/or command files


HPVERSION_1389
HPVERSION

HPVERSION           [STR]     MPE version id (v.uu.ff)


HPWAITJOBS_1390
HPWAITJOBS

HPWAITJOBS          [INT]     Number of jobs currently in a WAIT state.


HPYEAR_1391
HPYEAR

HPYEAR              [INT]     The current year (1 to 99).


Advanced_expression_programming__1392
Advanced expression programming

The expression operators and functions that we described above had to do with
what we might call "simple expressions" -- expressions that operate on several
things (constants, variables, etc.) and return a value.  MPEX's %CALC, %SETVAR,
%IF, STREAMX ;CHECK= conditions, etc.  all use "simple expressions" like that.

In certain circumstances, though -- for instance, in the flexible LISTF files
-- you want more than just an expression.  What you want is more like a
program, with a sequence of statements, each to be executed in turn.  This
program should be able to have variables, assignment statements, IF statements,
WHILE loops, WRITELN statements to output things, etc.  -- all the power of a
true programming language.

Here, for instance, is a snippet from what might be an MPEX flexible LISTF
file:

   VAR I: INTEGER;
   VAR S: STRING[120];

   I:=10;
    ...
   IF I>20 AND S<>'FOO' THEN
     WHILE I<>0 DO
       BEGIN
       WRITELN (S);
        ...
       END
   ELSE
      ...;

As you see, this looks much like a PASCAL program, and has most of the power of
PASCAL.  Statements are separated by ";"s; variables can be declared, assigned
to, and used; IF ...  THEN ...  ELSE and WHILE ..  DO loops are available;
BEGIN ...  END can be used to group several statements into one.

In addition to flexible LISTF files, MPEX expression programs can be used to do
advanced tasks that regular command files are too slow for (although expression
programs are still slower than regular, compiled programs).  For more details
on writing expression programs, see "Expression Programs -- A Powerful Feature
For Sophisticated Users" below.

IF ... THEN ... ELSE


IF_1393
IF


THEN_1394
THEN


ELSE_1395
ELSE
Conditional processing is quite simple; in fact, it's almost identical to
PASCAL's:

   IF condition THEN
     statement
   ELSE
     statement;

For instance,

   IF I>20 AND S MATCHES 'X@' THEN
     WRITELN ('HELLO')
   ELSE
     WRITELN ('GOOD BYE');


BEGIN_1396
BEGIN


END_1397
END
If you want to do more than one statement in either the THEN block or the ELSE
block, just use BEGIN ...  END:

   IF I>20 AND S MATCHES 'X@' THEN
     BEGIN
     WRITELN ('HELLO');
     WRITELN ('THERE')
     END
   ELSE
     BEGIN
     WRITELN ('GOOD');
     WRITELN ('BYE')
     END;

One new feature of the IF ...  THEN ...  ELSE is the ability to use them in an
"expression" context, i.e.  to return a value:

   WRITELN (IF I>20 THEN 55 ELSE 66);

Here, either 55 or 66 will be output, depending on whether I>20 is true or
false.

If you want an IF to return a value, the THEN block and the ELSE block must
return values of the same type --

   WRITELN (IF I>20 THEN 55 ELSE 'FOOBAR');

is illegal, since we have to know the type of the expression to be WRITELNed at
compile time.

Of course, if the IF doesn't return a value, it doesn't matter what the types
of the THEN and ELSE blocks are (in fact, they can then be BEGIN ...  END
constructs, which have no type).

WHILE ... DO


WHILE_1398
WHILE
Our WHILE ...  DO loops are identical to PASCAL's.  If you say

   WHILE condition DO
     statement;

then the statement will be executed again and again as long as the condition is
true.  BEGINs and ENDs can be used if you want to execute more than one
statement:

   WHILE I<=100 DO
     BEGIN
     WRITELN (I:10, I*I:10, I*I*I:10);
     I:=I+1;
     END;

Constructs like  REPEAT ...  UNTIL or a FOR x := y TO z DO can be easily
emulated with the WHILE loop.

FOR stringvar IN FILE (fopenparms) DO


FOR_1399
FOR
This form of our FOR loop allows you to process all of the records in a file.
The full syntax is:

   FOR stringvar IN FILE (fopenparms) DO
      statement;

For example, to search through a list of files and report on any files that are
missing:

   VAR FILENAME_TO_TEST: STRING[68];
   FOR FILENAME_TO_TEST IN FILE ("FILELIST,OLD") DO
      IF NOT FEXISTS(FILENAME_TO_TEST) THEN
         WRITELN ("File ",RTRIM(FILENAME_TO_TEST)," is missing!");

Here is a more advanced example that implements a new command.  If you keep
this as a file named PURGETMP (with filecode 171 -- see "Writing Expression
Programs" below), you can say

   %PURGETMP @.@.@

to purge all of your temporary files.

Here is the expression program itself:

   VAR TEMPFILENAME: STRING[68];
   FOR TEMPFILENAME IN FILE (STDLIST('LISTFTEMP '+VEPARMS)) DO
     BEGIN
       IF TEMPFILENAME MATCHES "@.@.@" THEN BEGIN
         WRITELN ("-----PURGETMPing ",RTRIM(TEMPFILENAME));
         MPE ("PURGE "+TEMPFILENAME+",TEMP");
       END;
     END

What does all of this mean?

   * Well, VEPARMS is a predefined variable containing the parameters passed to
     the expression program;

   * the STDLIST function (documented earlier in this Appendix) executes an MPE
     command (in this case, "LISTFTEMP"), writes the output of the command to a
     temporary file, and returns the fopenparms needed to open that file and
     then automatically purge it when you close it;

   * "FOR TEMPFILENAME IN FILE..." reads the file created by the STDLIST
     function, and puts each line in turn into the variable "TEMPFILENAME";

   * we check to make sure TEMPFILENAME contains a filename (to skip past the
     heading portion of the output of the LISTFTEMP command), and if it does,

   * we show the user the name of the file ("WRITELN..."), and, finally,

   * we call the MPE function to purge the file!

TRY ... RECOVER and TRY ... CLEANUP


TRY_____RECOVER_1400
TRY ... RECOVER


TRY_____CLEANUP_1401
TRY ... CLEANUP
If you want to do your own error handling in the file, you can use two
constructs -- TRY ...  RECOVER (analogous to the %TRAPERROR/%IFERROR) and TRY
...  CLEANUP (analogous to the %TRAPERROR/%CLEANUP).

   TRY
      stmt1
   RECOVER
      stmt2

does stmt1 (which can be either a single statement or a BEGIN/END block), and
if an error occurs, does stmt2 and then continues with the remainder of the
program.

   TRY
      stmt1
   CLEANUP
      stmt2

does stmt2 after doing stmt1, whether or not an error occurred in stmt1;
however, if an error did occur, it aborts the program after doing stmt2.  Thus,
a common sequence that you might use for file handling would be:

   FNUM:=VEFOPEN ...;
   TRY
     BEGIN
      ...
     END
   CLEANUP
     VEFCLOSE (FNUM);

EXPRESSION PROGRAM VARIABLES


VAR_1402
VAR


Expression_program_variables_1403
Expression program variables
We support variables of several types:

   INTEGER         32-bit integer
   BOOLEAN         TRUE or FALSE
   REAL            32-bit floating point (single-precision real)
   DATE            date
   TIME            time
   STRING[xxx]     variable-length string of up to xxx characters

To declare a variable, just say

   VAR varname: type;

e.g.

   VAR LINECOUNT: INTEGER;
   VAR HEADER: STRING[256];

You must have exactly one variable per VAR statement -- both

   VAR LINECOUNT, XYZZY: INTEGER;   (* illegal! *)

and

   VAR LINECOUNT: INTEGER;
       XYZZY: INTEGER;              (* illegal! (no second VAR) *)

are illegal.  Instead, say

   VAR LINECOUNT: INTEGER;
   VAR XYZZY: INTEGER;

All VAR statements must come at the beginning of the "expression program" in
which they'll be used.

Once you've declared a variable, you can assign to it by saying

   variable := expression;

e.g.

   I := I * 17;
   S := 'TESTING ONE TWO THREE';

The left-hand side of an assignment statement can only be

   * a variable (I := 17), or

   * a substring (S[3:4] := 'XYZZ') -- in this case, the entire substring must
     be within the bounds of the string.

In particular, neither expressions nor MPEX variables (or MPE/iX variables) may
be put on the left-hand side of an assignment statement.  To set MPEX
variables, use the BVARSET, IVARSET, and SVARSET functions, or the MPEX %SETVAR
command.

After you've assigned a value to a variable, you can use it much as you'd be
able to use a file attribute variable or an MPEX variable:

   IF I>10 THEN
     WRITELN (S);

Note that variables declared with a VAR command are strictly local variables,
local to the "expression program" that declares them.  They can not be later
referenced in an MPEX command, whether in a %CALC, %SETVAR, ! substitution
construct, or what have you.

Sorry, no record structures (yet?).  Also, be wary of declaring long strings!
You have a very limited amount of space left (if you exhaust it, it's STACK
OVERFLOW time).

OUTPUTTING DATA

Every good language should have a good input and output mechanism (SPL is a
notable offender in this area).  For input, you can use the READxxx functions
discussed above (READINTEGER, READSTRING, READDATE, etc.).  For output, you can
use:


WRITELN_1404
WRITELN
   WRITELN (value1, value2, ..., valueN);

and


WRITEPROMPT_1405
WRITEPROMPT
   WRITEPROMPT (value1, value2, ..., valueN);

Both are just like STRWRITE except that they output to the terminal (or
whatever the list file of the expression program is) instead of returning a
string.  WRITELN outputs the data and then a carriage return/line feed;
WRITEPROMPT outputs it without a CR/LF.


WRITE_1406
WRITE
   WRITE (value1, value2, ..., valueN);

formats all the values but doesn't actually output them.  Instead, the
formatted text is kept in the "output buffer"; subsequent WRITEs, WRITELNs, and
PROMPTs will append to this output buffer, until it's actually output (and
cleared) by a WRITELN or a WRITEPROMPT.  Thus,

   WRITE ('FOO');
   WRITE ('BAR');
   WRITELN ('XYZ');

will output "FOOBARXYZ".  If you have stuff in the output buffer and you want
to throw it away, you can say


CANCELWRITE_1407
CANCELWRITE
   CANCELWRITE ();

(the open and close parentheses are important).

Other I/O constructs include:


WRITEPAGE_1408
WRITEPAGE
   * WRITEPAGE()

     This causes a form feed on the expression program output file.

COMMENTS


Comments_in_expression_programs_1409
Comments in expression programs
You can insert comments in expression programs by enclosing them in "(*" and
"*)".  For example,

   ...
   (* Figure out the month number for a three-letter abbreviation *)
   MONTH:=(POS(UPS(MONTHSTR[0:3]),
        "JAN FEB MAR APR MAY JUN JUL AUG SEP OCT NOV DEC ")
        +3)/4;  (* Remember, POS starts counting at 1 *)
   ...


Comments_in_SECURCON_files_1410
Comments in SECURCON files


Comments_in_STREAMX_files_1411
Comments in STREAMX files


Comments_in_LOGOFF_files_1412
Comments in LOGOFF files


Comments_in_LOGOFFAB_files_1413
Comments in LOGOFFAB files


Comments_in_LOGOFFWR_files_1414
Comments in LOGOFFWR files
This feature may also be used to add comments to the following files:

   SECURCON.DATA.VESOFT
   STREAMX.DATA.VESOFT
   LOGOFF.DATA.VESOFT
   LOGOFFAB.PUB.VESOFT
   LOGOFFWR.PUB.VESOFT


Writing_expression_programs__1415
Writing expression programs

Especially now that MPEX can access files, there are many things that you can
do in MPEX that you used to need a program to do.  However, MPEX command files
are much slower than programs, because every command has to be interpreted;
thus, using a %WHILE loop to read a file might take you a tenth of a second or
more per record.

You can do things much quicker (though still more slowly, perhaps by as much as
a factor of 10 or more, than in a program) using VESOFT expression programs.
You may have already used expression programs if you've written flexible LISTF
files -- they are much like simple VESOFT expressions, in that you can use all
the functions that you can use in %CALC, %IF, etc., but you can also declare
variables and use constructs like IF/THEN/ELSE, WHILE, BEGIN/END, etc.  --
these are all documented above under "Advanced Expression Programming".


Filecode_171_1416
Filecode 171
In order to create an expression program, simply write it with your favorite
text editor and /KEEP it as a file with filecode 171 (you can use MPEX's
%ALTFILE fileset;CODE=171).  You can then execute it by just typing its name at
the % prompt, just like a command file (HPPATH is honored for this just as it
is for command files and programs).


Filecode_176_1417
Filecode 176
The first time you execute any expression program, MPEX "compiles" it into a
file with the same name, in the same group and account, but with a "9" appended
to the end of the filename (or the last character changed to a "9" if the
filename is already 8 characters long; or, if the filename is 8 characters and
already ends in 9, the new file will end in "8").  This new file will have
filecode 176.


MPE_V_and_MPE_iX_differences__compiled_exp_progs_1418
MPE/V and MPE/iX differences: compiled exp progs
If you are using the Native Mode version of MPEX, compiled expression programs
will end in 8 (or 7) instead of 9 (or 8).

Note: you must be careful not to create 2 different expression programs in the
same group.account with the filename the same for the first 7 characters.

For safety's sake, if there is an existing file with the filename that the
expression program is supposed to be compiled into, but it doesn't have
filecode 176, MPEX will not overwrite, but will instead print an error message
(your new expression program will not run).  If this happens, simply PURGE or
RENAME the "9"-file.

For example, if you create an expression program named MYEXPROG.MYGROUP.MYACCT
(with file code 171), then type

   %MYEXPROG

MPEX will compile MYEXPROG into a new file named MYEXPRO9.MYGROUP.MYACCT (for
CM users) or MYEXPRO8.MYGROUP.MYACCT (for NM users), with filecode 176, and
then execute it.  The next time you execute it (provided you haven't modified
MYEXPROG in the meantime), it will execute much faster, since it has already
been "compiled".  Note that you never say %MYEXPRO9 or %MYEXPRO8; always use
the name of the original file (in this case, MYEXPROG).

Whenever you make a change to any expression program, it will be automatically
re-compiled the next time you execute it.  This "pre-compiling" helps make
expression programs execute much faster.


VEPARMS_1419
VEPARMS
Any parameters that were specified are passed to the command file as the
variable VEPARMS (it is your job to parse it, probably using TOKEN and
REMTOKEN).  Here's an example:

  VAR S: STRING[256];
  VAR I: INTEGER;
  VAR FNUM: INTEGER;

  I:=0;
  FNUM:=VEFOPEN (VEPARMS+',OLD');
  S:=VEFREAD (FNUM);
  WHILE NOT VEEOF DO
    BEGIN
    I:=I+INTEGERPARSE (S);
    S:=VEFREAD (FNUM);
    END;
  VEFCLOSE (FNUM);
  WRITELN ('Sum of lines is ', I);

This expression program opens a file (whose name is given as the parameter to
the expression program) and sums the integer values stored in all of its
records -- just an example of what you can do.  An alternative to the above
would be:

  VAR S: STRING[256];
  VAR I: INTEGER;
  I:=0;
  FOR S IN FILE (VEPARMS+',OLD') DO
    I:=I+INTEGERPARSE (S);
  WRITELN ('Sum of lines is ', I);

The  FOR stringvar IN FILE (fopenparms) DO statement performs that statement
for each record in the file, assigning the value of the record to stringvar.
This saves you from having to do your own VEFOPEN, VEFREAD, and VEFCLOSE, and
also properly closes the file in case an error occurs.

A VERY IMPORTANT DISCLAIMER

I hesitated a lot before releasing this feature, since it should not be viewed
as a general-purpose programming language.  It is limited in a number of ways,
and you should be aware of these ways before you invest any serious time into
using it.

   * It is, and always will be, slower -- maybe much slower -- than a
     third-generation-language program.  Though we "compile" the expression
     program, we compile it into a kind of pseudo-code that we then interpret.

   * Expression programs lack many features that are necessary for a really
     general-purpose programming language, e.g.  record structures, procedures,
     etc.  On the other hand, it does have a lot of nice things -- like
     convenient file access and string manipulation -- that most languages
     don't have.

Although we'll entertain enhancement requests to work around these problems,
they'll have a substantially lower priority than other enhancement requests,
and we'll often expect you to live with workarounds that might be less than
perfect.  Historically, expression programs were developed to allow VESOFT to
implement its own features (like most MPEX commands, all the %SEC commands, and
a very great part of VEAUDIT), and we've made them available to users because
we had already created them for ourselves.  Especially because we expect only
rather sophisticated users to use expression programs, we probably won't
implement many features unless they're useful to ourselves.

One other note -- curious people may look at files in the VESOFT account and
try to use in their own expression programs the features that they see us use
in ours.  However, for security reasons, the features we make available to
users are a subset of those features we use internally.  Some of those features
will actually give you errors if you try to use them yourselves; even if, by
accident, you can get them to work, we will not support them unless they are
documented.

We've put in these disclaimers because we don't want to create any expectations
that we can't live up to, or have you invest a lot of effort into trying to do
things with this feature that it was never intended to do.  On the other hand,
for short, simple problems, we feel that expression programs can be a really
powerful solution.


B__1420
B-

Loader error messages, usually generated at :RUN command execution time, can
best be described in one word: CRYPTIC.  They usually do not tell you what the
problem is, and they never tell you how to remove or get around the problem.
The Error Messages and Recovery Manual or the Error Messages appendix of the
System Intrinsics Manual is not much help either -- more often than not, no
explanation is given, save a repetition of the text of the message.  The
following is a feeble effort at cataloging explanations and workarounds to some
of the more frequently occurring error messages:


B__1421
B-
20 ILLEGAL LIBRARY SEARCH  (LOAD ERR 20):

   Either 1) An attempt was made to run a program in the PUB group of the SYS
   account with LIB=G or LIB=P, or 2) an invalid library search parameter was
   specified in the CREATE or LOADPROC intrinsic call.

   WORKAROUND:  In case 1) since LIB=G, LIB=P, and LIB=S (default) are
   functionally equivalent for programs in PUB.SYS, the program should be run
   with LIB=s or the LIB= clause should be omitted; in case 2, a valid library
   search parameter should be specified.


B__1422
B-
21 UNKNOWN ENTRY POINT  (LOAD ERR 21):

   A program was run with an entry point which does not exist in the program
   file.

   WORKAROUND: Specify an entry point that exists in the file.


B__1423
B-
22 TRACE SUBSYSTEM NOT PRESENT  (LOAD ERR 22):

   Your SPL or FORTRAN program uses the $TRACE keyword, but TRACE/3000 is not
   installed on your system.

   WORKAROUND:  Remove the $TRACE keyword and recompile.  You don't REALLY use
   TRACE/3000, do you?


B__1424
B-
23 STACK SIZE TOO SMALL  (LOAD ERR 23):

   The stack size with which the program was to be run was less than 512.

   WORKAROUND: Specify a bigger stack size.


B__1425
B-
24 MAXDATA TOO LARGE   (LOAD ERR 24)

   This error is no longer used.


B__1426
B-
25 STACK SPACE REQUIRED EXCEEDS SPECIFIED MAXDATA  (LOAD ERR 25):

   The maxdata specified is not large enough to fit the initial stack of the
   program to be run.

   WORKAROUND: Specify a larger maxdata or decrease the program's stack usage.


B__1427
B-
26 PROGRAM LOADED IN OPPOSITE MODE  (LOAD ERR 26):

   An attempt was made to run with the ;NOPRIV keyword a program that is
   already loaded (run or allocated) without the ;NOPRIV keyword, or vice
   versa.

   WORKAROUND: Run the program with or without the ;NOPRIV keyword, whichever
   is appropriate.


B__1428
B-
27 SL BINDING ERROR  (LOAD ERR 27):

   The program to be loaded has external references to procedures that cannot
   be found in the SL files with which the program is to be loaded.

   WORKAROUND: Correct the program so it will not refer to those procedures,
   add those procedures to the SL file, or, if the procedures are present in
   the group SL or the PUB group SL, run the program with LIB=G or LIB=P.


B__1429
B-
28 INVALID SYSTEM SL FILE  (LOAD ERR 28):

   Your SL.PUB.SYS is not a valid SL file.  Boy, are you in deep trouble!

   WORKAROUND: Do a COLDLOAD or an UPDATE (or, even better, a RELOAD).  While
   you're at it, call your SE, too.


B__1430
B-
29 INVALID PUBLIC SL FILE  (LOAD ERR 29):

   The PUB group SL file with which the program was to be loaded is not a valid
   SL file.

   WORKAROUND: Run the program with LIB=S, replace the PUB group SL file with a
   valid SL file, or purge the PUB group SL file.  It is usually a good idea to
   avoid using the name 'SL' for non-SL files.


B__1431
B-
30 INVALID GROUP SL FILE  (LOAD ERR 30):

   The group SL file with which the program was to be loaded is not a valid SL
   file.

   WORKAROUND:  Run the program with LIB=G or LIB=P, replace the group SL file
   with a valid SL file, or purge the group SL file.  It is usually a good idea
   to avoid using the name 'SL' for SL files.


B__1432
B-
31 INVALID PROGRAM FILE  (LOAD ERR 31):

   The file to be loaded is not a valid program file (i.e.  does not have
   filecode PROG).

   WORKAROUND: Do not try to run the specified file.


B__1433
B-
32 INVALID LIST FILE  (LOAD ERR 32)


B__1434
B-
33 CODE SEGMENT TOO LARGE  (LOAD ERR 33):

   One of the program file's code segments is larger than the maximum permitted
   by your system configuration.

   WORKAROUND: Re-segment the program file or get the system manager to
   increase the maximum code segment size for your system (NOTE: The MPE V
   System Manager/System Supervisor Manual suggests to set this parameter to 5%
   of available memory; i.e.  systems with 768 Kilobytes or more of memory
   should have this parameter set to 16384 words, the maximum possible).


B__1435
B-
34 PROGRAM FILE'S EXTENT MAXIMUM MUST BE ONE  (LOAD ERR 34):

   A program file must have its maximum number of extents equal to 1.

   WORKAROUND:  Do not run this program file or change its number of extents
   (possibly with the %ALTFILE ,EXTENTS= command of VESOFT's MPEX/3000
   utility).


B__1436
B-
35 DATA SEGMENT TOO LARGE  (LOAD ERR 35):

   The total amount of stack data segment space (including stack, system
   overhead, and stack expansion area) necessary for this program exceeds the
   system maximum of 32K.

   WORKAROUND:  Decrease the amount of stack space used by the program.  It is
   usually a good idea to keep this quantity less than 25 to 30 thousand words.


B__1437
B-
36 DATA SEGMENT TOO LARGE  (LOAD ERR 36):

   The total amount of stack data segment space (including stack, system
   overhead, and stack expansion area) necessary for this program exceeds the
   configuration maximum.

   WORKAROUND: Decrease the amount of stack space used by the program or
   increase the configuration maximum.


B__1438
B-
37 TOO MANY CODE SEGMENTS  (LOAD ERR 37):

   The program file to be run contains more than 63 segments, the maximum
   allowed by the system.

   WORKAROUND:  Re-segment the program so it will have less than 63 segments,
   or separate the functions of the program into two or more different programs
   (possibly linked via Process Handling).


B__1439
B-
38 TOO MANY CODE SEGMENTS  (LOAD ERR 38):

   The program file to be run contains more code segments than the
   configuration maximum.

   WORKAROUND: Re-segment the program to decrease the number of code segments,
   separate the functions of the program into two or more different programs
   (possibly linked via Process Handling), or increase the configuration
   maximum.


B__1440
B-
39 ILLEGAL CAPABILITY  (LOAD ERR 39):

   Either:

   1) The program to be run has a capability (e.g.  PH, PM, MR, or DS) that the
      group in which it resides or the account in which it resides does not
      have,
   2) The program is a TEMPORARY FILE and has a capability that the
      user who's running it doesn't have,
   3) The program is being run online, but lacks IA capability, or is
      being run offline but lacks BA capability, or
   4) The program contains a privileged segment but lacks PM
      capability.

   WORKAROUND:

   1) The group or account in which the program resides (not the user running
      the program!) should be given all the capabilities that the program has,
      OR some of the capabilities should be taken away from the program (e.g.
      with the %ALTFILE ,CAP= command of VESOFT's MPEX/3000);
   2) The user running the program should be given the appropriate
      capabilities, or the program should have capabilities taken away from it,
      or it should be :SAVEd and then treated as a temporary file (as in case
      1);
   3) The program should be either given the missing capability (IA
      or BA) or run in the right mode (offline or online);
   4) The program should either be given PM capability or have its
      privileged segments removed.


B__1441
B-
40 TOO MANY PROCEDURES LOADED  (LOAD ERR 40):

   An attempt was made to load (via the LOADPROC intrinsic) more than
   (approximately) 250 procedures.

   WORKAROUND: Do not attempt to do more than 250 LOADPROCs.  NOTE: Unloading
   some of the procedures loaded (via the UNLOADPROC intrinsic) will not help!


B__1442
B-
41 UNKNOWN PROCEDURE NAME  (LOAD ERR 41):

   The procedure which was to be loaded (via the LOADPROC intrinsic) does not
   exist in the SL file(s) from which it was to be loaded.

   WORKAROUND: Do not try to load this procedure, add a procedure with this
   name to the SL file, or, if the procedure already exists in a different SL
   file, specify a different library search parameter in the LOADPROC
   invocation.


B__1443
B-
42 INVALID PROCEDURE NUMBER  (LOAD ERR 42)

   This message is no longer used.


B__1444
B-
43 ILLEGAL PROCEDURE UNLOAD  (LOAD ERR 43)

   This message is no longer used.


B__1445
B-
44 ILLEGAL SL CAPABILITY  (LOAD ERR 44):

   The SL with which this program was to be run has privileged procedures, but
   does not reside in a group and account with PM capability.

   WORKAROUND:  Remove the privileged procedure from the SL, give PM capability
   to the group and account in question, or do not use this SL.


B__1446
B-
45 INVALID ENTRY POINT  (LOAD ERR 45)

   The entry point specified for the program or procedure to be loaded was
   found, but it pointed to invalid code segment information.

   WORKAROUND: The problem is not with the entry point you specified, but is
   with the program file itself.  Recompile the program and try again.


B__1447
B-
46 TEMPORARY PROGRAM FILE ILLEGAL  (LOAD ERR 46)

   An attempt was made to load a program that is in the temporary file domain.
   Only files in the permanent file domain can be allocated.

   WORKAROUND: Make the file permanent with the SAVE command, and try again.


B__1448
B-
50 UNABLE TO OPEN SYSTEM SL FILE  (LOAD ERR 50):

   The file in question cannot be opened.  Possible reasons are that the file
   is opened exclusively, its file label is clobbered.

   WORKAROUND:  Do not use the SL file in question; or, determine exactly why
   the file cannot be opened and take appropriate action.


B__1449
B-
51 UNABLE TO OPEN PUBLIC SL FILE  (LOAD ERR 51):

   The file in question cannot be opened.  Possible reasons are that the file
   is opened exclusively, its file label is clobbered.

   WORKAROUND:  Do not use the SL file in question; or, determine exactly why
   the file cannot be opened and take appropriate action.


B__1450
B-
52 UNABLE TO OPEN GROUP SL FILE  (LOAD ERR 52):

   The file in question cannot be opened.  Possible reasons are that the file
   is opened exclusively, its file label is clobbered,

   WORKAROUND:  Do not use the SL file in question; or, determine exactly why
   the file cannot be opened and take appropriate action.


B__1451
B-
53 UNABLE TO OPEN PROGRAM FILE  (LOAD ERR 53):

   The file in question cannot be opened.  Possible reasons are that the file
   is opened exclusively, its file label is clobbered.

   WORKAROUND:  Do not run the program in question or determine exactly why the
   file cannot be opened and take appropriate action.


B__1452
B-
54 UNABLE TO OPEN LIST FILE  (LOAD ERR 54)

   The LOADLIST file cannot be opened.  The file might be open exclusively or
   its file label might be defective.

   WORKAROUND: If an asterisk (*) appears after the filename when you execute
   the command "LISTF <filename>,2", the problem might be that another process
   has exclusive access to the file.  If not, then the file might need to be
   recreated, or the operating system might need to be reloaded.


B__1453
B-
55 UNABLE TO CLOSE SYSTEM SL FILE  (LOAD ERR 55)

   A process attempted to close the SL file SL.PUB.SYS, but the close was not
   successful.

   This error condition could indicate a corrupt file or a problem with the
   operating system.  Report this error to your system administrator.

   WORKAROUND: Perform an UPDATE/START to put a new copy of the System SL file
   on your system.


B__1454
B-
56 UNABLE TO CLOSE PUBLIC SL FILE  (LOAD ERR 56)

   A process attempted to close the SL file in the PUB group, but the close was
   not successful.

   This error condition could indicate a corrupt file or a problem with the
   operating system.  Report this error to your system administrator.

   WORKAROUND: Restore a new copy of the SL from a known good backup.


B__1455
B-
57 UNABLE TO CLOSE GROUP SL FILE  (LOAD ERR 57)

   A process attempted to close the group SL file, but the close was not
   successful.

   This error condition could indicate a corrupt file or a problem with the
   operating system.  Report this error to your system administrator.

   WORKAROUND: Restore a new copy of the SL from a known good backup.


B__1456
B-
58 UNABLE TO CLOSE PROGRAM FILE  (LOAD ERR 58)

   A process attempted to close a program file, but the close was not
   successful.

   This error condition could indicate a corrupt file or a problem with the
   operating system.  Report this error to your system administrator.

   WORKAROUND: Recompile or Restore a good copy of the program file.


B__1457
B-
59 UNABLE TO CLOSE LIST FILE  (LOAD ERR 59)

   A process attempted to close a list file, but the close was not successful.

   This error condition could indicate a corrupt file or a problem with the
   operating system.  Report this error to your system administrator.


B__1458
B-
60 EOF OR I/O ERROR ON SYSTEM SL FILE  (LOAD ERR 60).

   The program to be loaded could not be run because the loader got an
   end-of-file indication or I/O error while reading the specified file.  This
   could mean that 1) the specified file is messed up, or 2) the specified file
   could not be accessed because it is currently being STOREd (this condition
   often occurs during a SYSDUMP).

   WORKAROUND: In case 1, correct the file in question; in case 2, wait until
   STORE or SYSDUMP unlocks the file, or (in case the error occurs on the
   program file) copy the program file into another file and then run the new
   file.


B__1459
B-
61 EOF OR I/O ERROR ON PUBLIC SL FILE  (LOAD ERR 61).

   The program to be loaded could not be run because the loader got an
   end-of-file indication or I/O error while reading the specified file.  This
   could mean that 1) the specified file is messed up, or 2) the specified file
   could not be accessed because it is currently being STOREd (this condition
   often occurs during a SYSDUMP).

   WORKAROUND: In case 1, correct the file in question; in case 2, wait until
   STORE or SYSDUMP unlocks the file, or (in case the error occurs on the
   program file) copy the program file into another file and then run the new
   file.


B__1460
B-
62 EOF OR I/O ERROR ON GROUP SL FILE  (LOAD ERR 62).

   The program to be loaded could not be run because the loader got an
   end-of-file indication or I/O error while reading the specified file.  This
   could mean that 1) the specified file is messed up, or 2) the specified file
   could not be accessed because it is currently being STOREd (this condition
   often occurs during a SYSDUMP).

   WORKAROUND: In case 1, correct the file in question; in case 2, wait until
   STORE or SYSDUMP unlocks the file, or (in case the error occurs on the
   program file) copy the program file into another file and then run the new
   file.


B__1461
B-
63 EOF OR I/O ERROR ON PROGRAM FILE  (LOAD ERR 63).

   The program to be loaded could not be run because the loader got an
   end-of-file indication or I/O error while reading the specified file.  This
   could mean that 1) the specified file is messed up, or 2) the specified file
   could not be accessed because it is currently being STOREd (this condition
   often occurs during a SYSDUMP).

   WORKAROUND: In case 1, correct the file in question; in case 2, wait until
   STORE or SYSDUMP unlocks the file, or (in case the error occurs on the
   program file) copy the program file into another file and then run the new
   file.


B__1462
B-
64 EOF OR I/O ERROR ON LIST FILE  (LOAD ERR 64)

   The program to be loaded could not be run because the loader got a file
   system error while reading the list file.

   WORKAROUND: The list file might be corrupt, or STORE or SYSDUMP might have
   the file locked.  Contact your support representative if problems persist.


B__1463
B-
65 UNABLE TO OBTAIN CST ENTRIES  (LOAD ERR 65)

   The loader could not get enough Code Segment Table entries for the program
   or procedure being loaded.

   WORKAROUND: A code segment cannot be larger than 37777 words.  An SL can
   contain no more than 255 segments, and a program file can contain no more
   than 152 segments.  Try deallocating a procedure not in use.


B__1464
B-
66 UNABLE TO OBTAIN PROCESS DST ENTRY  (LOAD ERR 66)

   The loader could not allocate a DST entry for the process being loaded.

   WORKAROUND: Try DEALLOCATEing a procedure not in use or increasing the size
   of the DST.


B__1465
B-
67 UNABLE TO OBTAIN MAIL DATA SEGMENT  (LOAD ERR 67)

   This message is no longer used.


B__1466
B-
68 UNABLE TO CREATE LOAD PROCESS  (LOAD ERR 68)

   This message is no longer used.


B__1467
B-
69 UNABLE TO OBTAIN CSTX ENTRIES  (LOAD ERR 69)

   This message is no longer used.


B__1468
B-
70 SEGMENT TABLE OVERFLOW  (LOAD ERR 70)

   The loader was unable to load the program or procedure because the loader
   segment table is full.

   WORKAROUND: Increase the size of the Loader Segment Table if possible, or
   use the DEALLOCATE command to unload unnecessary programs.


B__1469
B-
71 UNABLE TO OBTAIN SUFFICIENT DL STORAGE  (LOAD ERR 71)

   The loader could not get enough DL area.  This is a system problem.

   WORKAROUND: Try to reduce the amount of SL libraries or external procedures
   being referenced.  For example, you might merge group and account SL
   libraries.

   Contact your support representative if this occurs.


B__1470
B-
72 ATTIO ERROR  (LOAD ERR 72):

   The loader could not modify the program file's file label.

   WORKAROUND:  None.  The file label may be clobbered, or you may be having
   hardware problems.


B__1471
B-
73 UNABLE TO OBTAIN VIRTUAL MEMORY  (LOAD ERR 73)

   Virtual memory was not available when the stack was being created.

   WORKAROUND: Try again when the system is not as busy.  You may need to
   increase virtual memory on the system, or their might be a hardware problem.

   Contact your support representative if problems persist.


B__1472
B-
74 DIRECTORY I/O ERROR  (LOAD ERR 74):

   The loader could not retrieve the directory entry of the group in which the
   program file resides.

   WORKAROUND: None.  Your directory may be clobbered, or you may be having
   hardware problems.


B__1473
B-
75 PRINT I/O ERROR  (LOAD ERR 75):

   The loader got an I/O error while printing a warning (LOAD WARN 89, 90, 91,
   or 92).

   WORKAROUND:  None.  You may be having hardware problems.


B__1474
B-
76 ILLEGAL DLSIZE  (LOAD ERR 76):

   The dlsize with which the program is to be run exceed 32722 words, the
   maximum.  Note that even this hypothetical maximum is not attainable because
   dlsizes greater than approximately 27000 words cause the loader to generate
   a DATA SEGMENT TOO LARGE (LOAD ERR 35).

   WORKAROUND:  Specify a smaller dlsize.


B__1475
B-
77 ILLEGAL MAXDATA  (LOAD ERR 77)

   This message is no longer used.


B__1476
B-
80 PROGRAM ALREADY ALLOCATED  (LOAD ERR 80):

   An attempt was made to allocate a program that was already allocated.

   WORKAROUND: None necessary.  The program is already allocated.


B__1477
B-
81 ILLEGAL PROGRAM ALLOCATION  (LOAD ERR 81)

   An attempt was made to allocate a program that was already allocated.

   WORKAROUND: None necessary.  The program is already allocated.


B__1478
B-
82 PROGRAM NOT ALLOCATED  (LOAD ERR 82):

   An attempt was made to deallocate a program that was not allocated.

   WORKAROUND: None necessary.  The program is already deallocated.


B__1479
B-
83 ILLEGAL PROGRAM DEALLOCATION  (LOAD ERR 83)

   An attempt was made to deallocate a program that was not allocated.

   WORKAROUND: None necessary.  The program is already deallocated.


B__1480
B-
84 PROCEDURE ALREADY ALLOCATED  (LOAD ERR 84):

   An attempt was made to allocate a procedure that was already allocated.

   WORKAROUND: None necessary.  The procedure is already allocated.


B__1481
B-
85 ILLEGAL PROCEDURE ALLOCATION  (LOAD ERR 85):

   Allocation of system procedures (e.g.  FOPEN, ATTACHIO, etc.)  is not
   permitted.

   WORKAROUND:  None.


B__1482
B-
86 PROCEDURE NOT ALLOCATED  (LOAD ERR 86):

   An attempt was made to deallocate a procedure that was not allocated.

   WORKAROUND: None necessary.  The procedure is already deallocated.


B__1483
B-
87 ILLEGAL PROCEDURE DEALLOCATION  (LOAD ERR 87):

   Deallocation of system procedures (e.g.  FOPEN, ATTACHIO, etc.) is not
   permitted.

   WORKAROUND:  None.


B__1484
B-
88 LMAP NOT AVAILABLE  (LOAD WARN 88):

   The program was run with a request for an LMAP; however, the program was
   already loaded -- thus the LMAP could not be produced.

   WORKAROUND: Do without the LMAP, run the program when it is not loaded, or
   copy the program file into another file and then run it.


B__1485
B-
89 PROGRAM LOADED WITH LIB = G  (LOAD WARN 89):

   The program to be run was already loaded with a LIB= parameter other than
   the one with which it was to be run.  This means, for instance, that if you
   run a program X with LIB=G while it is already loaded with LIB=S (or LIB=P,
   for that matter), this message will come up and the program will be loaded
   with the same LIB= parameter as it is already loaded with.

   WORKAROUND: Ignore the message, run the program when it is not loaded, or
   copy the program file into another file, and then run it.


B__1486
B-
90 PROGRAM LOADED WITH LIB = P  (LOAD WARN 90):

   The program to be run was already loaded with a LIB= parameter other than
   the one with which it was to be run.  This means, for instance, that if you
   run a program X with LIB=G while it is already loaded with LIB=S (or LIB=P,
   for that matter), this message will come up and the program will be loaded
   with the same LIB= parameter as it is already loaded with.

   WORKAROUND: Ignore the message, run the program when it is not loaded, or
   copy the program file into another file, and then run it.


B__1487
B-
91 PROGRAM LOADED WITH LIB = S  (LOAD WARN 91):

   The program to be run was already loaded with a LIB= parameter other than
   the one with which it was to be run.  This means, for instance, that if you
   run a program X with LIB=G while it is already loaded with LIB=S (or LIB=P,
   for that matter), this message will come up and the program will be loaded
   with the same LIB= parameter as it is already loaded with.

   WORKAROUND: Ignore the message, run the program when it is not loaded, or
   copy the program file into another file, and then run it.


B__1488
B-
92 ATTEMPTING TO ALLOCATE PROGRAM FROM NON-SYSTEM DISC  (LOAD ERR 92):

   Allocation of programs that reside on private volumes is forbidden.

   WORKAROUND:  None.


B__1489
B-
93 UNABLE TO MOUNT PROGRAM FILE'S HOME VOLUME SET  (LOAD ERR 93):

   The home volume set of the indicated file cannot be mounted.

   WORKAROUND: Determine what caused the mount failure and take appropriate
   action.


B__1490
B-
94 UNABLE TO MOUNT SYSTEM SL'S HOME VOLUME SET  (LOAD ERR 94):

   The home volume set of the indicated file cannot be mounted.

   WORKAROUND: Determine what caused the mount failure and take appropriate
   action.


B__1491
B-
95 UNABLE TO MOUNT PUBLIC SL'S HOME VOLUME SET  (LOAD ERR 95):

   The home volume set of the indicated file cannot be mounted.

   WORKAROUND: Determine what caused the mount failure and take appropriate
   action.


B__1492
B-
96 UNABLE TO MOUNT GROUP SL'S HOME VOLUME SET  (LOAD ERR 96):

   The home volume set of the indicated file cannot be mounted.

   WORKAROUND: Determine what caused the mount failure and take appropriate
   action.


B__1493
B-
97 UNABLE TO LOAD REMOTE PROGRAM FILE  (LOAD ERR 97):

   This message is no longer used.


B__1494
B-
98 UNABLE TO CONVERT OLD FORMAT  (LOAD ERR 98):

   This message is no longer used.


B__1495
B-
99 UNABLE TO OBTAIN DST FOR LOGICAL MAP  (LOAD ERR 99):

   The loader could not get a Data Segment Table entry for the logical map
   (LSTT).

   WORKAROUND: Try deallocating unused programs and procedures.  You may need
   to increase the DST size or the maximum configuration for extra data
   segment.  Virtual memory size might also need to be increased.


B__1496
B-
100 TOO MANY MAPPED SEGMENTS (LOAD ERR 100):

   Too many user SL segments were referenced.  The number of user SL segments
   cannot exceed 254.

   WORKAROUND: Reduce the amount of segments in the user SL.  Try combining
   some of the user SL segments for this program.


B__1497
B-
101 SEGMAP TOO BIG  (LOAD ERR 101):

   The loader was unable to allocate space in the logical map (LSTT).  The
   logical map is full.

   WORKAROUND: Reduce the amount of segments in the user SL.  Try combining
   some of the user SL segments for this program.


B__1498
B-
102 UNABLE TO EXPAND SEGMAP  (LOAD ERR 102):

   The loader was trying to allocate a larger data segment for the logical map
   (LSTT) when an error occurred.

   WORKAROUND: Try again when the system is not as busy.  Virtual memory might
   need to be increased or their might be a hardware problem.  Contact your
   support representative if problems persist.


B__1499
B-
103 TOO MANY DYNAMIC LOADS ON PROCEDURE  (LOAD ERR 103):

   A single process has attempted to load a procedure more than 65,535 times.
   This is probably a programming error since usually a procedure is loaded and
   then unloaded when not needed.

   WORKAROUND: Change the program logic to call UNLOADPROC to release the
   procedure when it is no longer needed.  Check for conditions that would load
   a procedure that was already loaded.


B__1500
B-
104 UNABLE TO OBTAIN DATA SEGMENT.  COMMAND IGNORED  (LOAD ERR 104):

   the SHOWALLOCATE command was not able to obtain a temporary extra data
   segment could not obtained as specified.

   WORKAROUND: Try deallocating unnecessary programs and procedures.  Increase
   the DST size or the maximum configuration for extra data segment size.
   Virtual memory size might also need to be increased.


B__1501
B-
105 UNABLE TO OPEN CONFDATA.PUB.SYS.  COMMAND IGNORED  (LOAD ERR 105):

   This message is no longer used.


B__1502
B-
106 EOF OR I/O ERROR ON CONFDATA.PUB.SYS.  COMMAND IGNORED  (LOAD ERR 106):

   This message is no longer used.


B__1503
B-
107 UNABLE TO CLOSE CONFDATA.PUB.SYS.  COMMAND IGNORED  (LOAD ERR 107):

   This message is no longer used.


B__1504
B-
108 EOF OR I/O ERROR ON SHOWALLOCATE LIST FILE.  COMMAND ABORTED (LOAD ERR
    108):

   The SHOWALLOCATE command had trouble using the list file specified with the
   command, or with $STDLIST if no file was specified.

   WORKAROUND: If you specified a file for output from this command, you might
   need to make it larger.  If it is large enough, the file label might be
   corrupt.  Check hardware and verify file label integrity.  Contact your
   support representative if problems persist.


B__1505
B-
109 I/O ERROR OCCURRED WHILE READING FILE LABEL.  COMMAND ABORTED (LOAD ERR
    109):

   The loader had a problem reading from the program file label.

   WORKAROUND: The file label might be corrupt.  Recompile the program, or
   restore it from a backup tape.  If this does not solve the problem, you
   might have a hardware problem, or you might need to reload the operating
   system by doing a COLDLOAD.  Contact your support representative if problems
   persist.


C__1506
C-

In addition to its other failings, the System Intrinsics Manual does not
explain the exact reason for and/or workaround for most file system errors.  In
fact, most file system error messages are very hard to understand.  The
following is an attempt at an adequate explanation of the causes, effects, and
workarounds for different file system errors that pertain to disc files:


C__1507
C-
0    END OF FILE (FSERR 0):

     This error is encountered when a program attempts to read beyond the end
     of file or write beyond the file limit.

     WORKAROUND: Change the program or the file.


C__1508
C-
1    ILLEGAL DB REGISTER SETTING (FSERR 1):

     Should never occur for non-privileged mode programs.  For privileged mode
     programs, this means that the programmer attempted to do an FFILEINFO,
     FGETINFO, FOPEN, or FRENAME in split-stack mode (i.e.  after a call to the
     EXCHANGEDB or SWITCHDB procedures).

     WORKAROUND: Do not perform the function in split-stack mode.


C__1509
C-
2    ILLEGAL CAPABILITY (FSERR 2):

     A function that requires privileged mode capability (e.g.  open a file for
     NOWAIT I/O, open a file for EXECUTE access, etc.) was attempted without
     privileged mode capability.

     WORKAROUND: Enter privileged mode before executing the function or do not
     attempt to execute it at all.


C__1510
C-
3    REQUIRED PARAMETER IS MISSING (FSERR 3):


C__1511
C-
4    DISC FREE SPACE ALLOCATION DISABLED ON ALL DISCS IN DOMAIN (FSERR 4):


C__1512
C-
5    DRT NUMBER > 511 (FSERR 5):


C__1513
C-
6    DEVICE HAS NO AVAILABLE SPARE BLOCKS (FSERR 6):


C__1514
C-
7    UNFORMATTED OR UNINITIALIZED MEDIA ON DEVICE.  (FSERR 7):


C__1515
C-
8    ILLEGAL PARAMETER VALUE (FSERR 8):

     Parameters specified in FOPEN call are mutually contradictory; for
     instance, an attempt to open a file NOWAIT on a serial disc was detected,
     or the program tried to open a new KSAM file without specifying the
     FORMALDESIGNATOR or KSAMPARAM parameters on the FOPEN.

     WORKAROUND: Correct the parameter.


C__1516
C-
9    INVALID FILE TYPE SPECIFIED IN FOPTIONS (FSERR 9):

     The file type field of the FOPEN file options is not one of 0 (STD =
     standard file), 1 (KSAM file), 2 (RIO file), 4 (CIR = circular file), or 6
     (MSG = message file).

     WORKAROUND: Correct the file type field.


C__1517
C-
10   INVALID RECORD SIZE SPECIFICATION (FSERR 10):

     The record size requested was more than 32,767 bytes.

     WORKAROUND: Specify a smaller record size.


C__1518
C-
11   INVALID RESULTANT BLOCK SIZE (FSERR 11):

     If the user requests were honored, the block size (BLOCK FACTOR * RECORD
     SIZE) of the resultant file would be greater than 32,767 bytes.

     WORKAROUND: Specify a smaller record size or blocking factor.


C__1519
C-
12   RECORD NUMBER OUT OF RANGE (FSERR 12):

     The user passed a negative record number to the FPOINT, FREADDIR, or
     FWRITEDIR intrinsic -- this is illegal.

     WORKAROUND: Correct your program.


C__1520
C-
13   CAN'T OPEN FILE MULTI-ACCESS, OUT OF FMAVT ENTRIES (FSERR 13):


C__1521
C-
15   EXCEEDED THE MAXIMUM MESSAGE FILE OPENS FOR WRITE ACCESS (FSERR 15):


C__1522
C-
16   MORE THAN 255 OPENS OF A FILE (FSERR 16):


C__1523
C-
17   MAGNETIC TAPE RUNAWAY (FSERR 17):


C__1524
C-
18   DEVICE POWERED UP (FSERR 18):


C__1525
C-
19   FORMS CONTROL WAS RESET (FSERR 19):


C__1526
C-
20   INVALID OPERATION (FSERR 20):


C__1527
C-
21   DATA PARITY ERROR (FSERR 21):


C__1528
C-
22   SOFTWARE TIME-OUT (FSERR 22):

     The user tried to read an empty message file or write to a full message
     file, an action which would cause the user to be impeded until the file
     was no longer empty or full, respectively (see MPE IV INTRINSICS MANUAL).
     However, a time out was set with the FCONTROL intrinsic (mode 4) and the
     request timed out before it could be honored.

     WORKAROUND: Do not set the time out, or ensure that the request can be
     serviced before it times out.


C__1529
C-
23   END OF TAPE (FSERR 23):


C__1530
C-
24   UNIT NOT READY (FSERR 24):


C__1531
C-
25   NO WRITE-RING ON TAPE (FSERR 25):


C__1532
C-
26   TRANSMISSION ERROR (FSERR 26):

     Hardware failure.

     WORKAROUND: Call your CE.


C__1533
C-
27   I/O TIME-OUT (FSERR 27):


C__1534
C-
28   TIMING ERROR OR DATA OVERRUN (FSERR 28):


C__1535
C-
29   SIO FAILURE (FSERR 29):

30   UNIT FAILURE (FSERR 30):

     Hardware failure.

     WORKAROUND: Call your CE.


C__1536
C-
31   END OF LINE (FSERR 31):


C__1537
C-
32   SOFTWARE ABORT (FSERR 32):


C__1538
C-
33   DATA LOST (FSERR 33):


C__1539
C-
34   UNIT NOT ON-LINE (FSERR 34):


C__1540
C-
35   DATA-SET NOT READY (FSERR 35):


C__1541
C-
36   INVALID DISC ADDRESS (FSERR 36):


C__1542
C-
37   INVALID MEMORY ADDRESS (FSERR 37):


C__1543
C-
38   TAPE PARITY ERROR (FSERR 38):


C__1544
C-
39   RECOVERY TAPE ERROR (FSERR 39):


C__1545
C-
40   OPERATION INCONSISTENT WITH ACCESS TYPE (FSERR 40):

     The access type specified at FOPEN time does not permit this operation;
     for instance, an FWRITE is not permitted when a file is opened with
     ACC=IN.

     WORKAROUND: Specify an access type at FOPEN time which permits this
     operation, or do not perform the operation at all.


C__1546
C-
41   OPERATION INCONSISTENT WITH RECORD TYPE (FSERR 41):

     It seems that this error should never show up and is merely a leftover
     from a previous version of MPE.


C__1547
C-
42   OPERATION INCONSISTENT WITH DEVICE TYPE (FSERR 42):

     The program tried to execute an operation that is incompatible with the
     device that it is trying to perform it on; for instance, it is trying to
     read the line printer or change the baud rate of a disc drive.

     WORKAROUND: Do not execute the operation.


C__1548
C-
43   WRITE EXCEEDS RECORD SIZE (FSERR 43):

     An attempt was made to write a record that would not fit in the
     destination file, e.g.  trying to write a 100-byte record into a file with
     a record length of 80 bytes.

     WORKAROUND: Change the file's record size, change the length of the record
     to be written, or open the file with the Multi-Record (MR) access option.


C__1549
C-
44   UPDATE AT RECORD ZERO (FSERR 44):

     The FUPDATE intrinsic (which is equivalent to the COBOL REWRITE statement)
     was called with the record pointer at record 0, which indicates that no
     record has been read and therefore no record can be updated.

     WORKAROUND: Call FPOINT or FREAD before the FUPDATE call.


C__1550
C-
45   PRIVILEGED FILE VIOLATION (FSERR 45):

     A program attempted to open a privileged file (one with a negative file
     code; e.g.  an IMAGE file) while specifying a filecode not equal to the
     file's filecode or while not in privileged mode.

     WORKAROUND: Enter privileged mode before the call or specify the correct
     filecode.


C__1551
C-
46   OUT OF DISC SPACE (FSERR 46):

     The device class on which this file resides (if this error occurs at
     extent allocation time) or is requested to reside (if this error occurs at
     file creation time) does not have enough contiguous disc space to
     accommodate this file; i.e.  if NUMEXTS is the number of extents to be
     allocated and EXTSIZE is the size (in sectors) of one extent, this device
     class does not have NUMEXTS contiguous chunks of EXTSIZE sectors each.

     WORKAROUND: Move the file to another, less full, device class, decrease
     the requested file size, or decrease the extent size by increasing the
     number of extents in the file.


C__1552
C-
47   I/O ERROR ON FILE LABEL (FSERR 47):

     The internal file label of this file cannot be accessed.  Most likely, the
     file is totally clobbered and will return INVALID FILE LABEL (FSERR 108)
     when it is subsequently accessed.

     WORKAROUND: None.


C__1553
C-
48   OPERATION INVALID DUE TO MULTIPLE FILE ACCESS (FSERR 48):

     One of the following conditions is true: 1) The program is trying to purge
     (i.e.  close with disposition DEL) a file that is currently loaded or
     being stored/restored, 2) The program is trying to rename (with the
     FRENAME intrinsic) a file that it does not have exclusive access to, or 3)
     The program is trying to open with LOCK access a file that someone else
     has opened with NOLOCK access or vice versa.

     WORKAROUND: 1) Don't purge the file or wait for the file to become
     purgeable again, 2) Don't rename the file or open the file with EXC
     access, or 3) Open the file with LOCK or NOLOCK access (whichever the
     other program has the file open with).


C__1554
C-
49   UNIMPLEMENTED FUNCTION (FSERR 49):

     The program specified an invalid parameter value in a file system
     intrinsic call; e.g.  a disposition of 5, 6, or 7 at FCLOSE time or a file
     type of RIO on pre-Athena systems (ones which do not support RIO files).

     WORKAROUND:  Correct your program.


C__1555
C-
50   NONEXISTENT ACCOUNT (FSERR 50):

     An attempt was made to open a file in an account which was not configured
     in the system.

     WORKAROUND:  Correct the filename or build the account.


C__1556
C-
51   NONEXISTENT GROUP (FSERR 51):

     An attempt was made to open a file in a group which was not configured in
     the system.

     WORKAROUND: Correct the filename or build the group.


C__1557
C-
52   NONEXISTENT PERMANENT FILE (FSERR 52):

     An attempt was made to open a file which does not exist.

     WORKAROUND: Correct the program or build the file.


C__1558
C-
53   NONEXISTENT TEMPORARY FILE (FSERR 53):

     The program tried to open a temporary file which does not exist.

     WORKAROUND: Correct the program or build the file.


C__1559
C-
54   INVALID FILE REFERENCE (FSERR 54):

     The program tried to open a file whose filename was invalid; for instance,
     the file, group, or account name was longer than 8 characters, an invalid
     system-defined file was specified (e.g.  $XYZZY), or no file equation was
     found for a back- referenced file (e.g.  *MANSION with no file equation
     for file MANSION).

     WORKAROUND: Correct the filename specified.


C__1560
C-
55   DEVICE UNAVAILABLE (FSERR 55):

     The program tried to open a message file that was already opened for MULTI
     (not GMULTI) access by another job/session.

     WORKAROUND: Wait for the other job/session to finish, or rewrite the other
     program to open the file NOMULTI or GMULTI.


C__1561
C-
56   INVALID DEVICE SPECIFICATION (FSERR 56):

     The device number or device class on which the file was to be opened is
     not configured on the system.

     WORKAROUND: Correct the program.


C__1562
C-
57   OUT OF VIRTUAL MEMORY (FSERR 57):

     The buffer size (NUMBER OF BUFFERS * RECORD SIZE * BLOCKING FACTOR) of the
     file to be opened exceeds 8,192 words (or 14,000 words starting with the
     D-MIT version of MPE IV).

     WORKAROUND: Decrease the number of buffers (by specifying BUF=1 on a :FILE
     equation, for instance), decrease the record size of the file, or decrease
     the blocking factor of the file.


C__1563
C-
58   NO PASSED FILE (FSERR 58):

     The program attempted to open $OLDPASS, but no $OLDPASS file exists.

     WORKAROUND: Correct the program or build a $OLDPASS file.


C__1564
C-
60   GLOBAL RIN UNAVAILABLE (FSERR 60):

     The program requested dynamic locking at file open time, but the RIN
     (Resource Identification Number) necessary for dynamic locking could not
     be obtained.

     WORKAROUND: Free some global RINs (with the :FREERIN command), file RINs
     (by closing files opened with LOCK access), open the file with NOLOCK
     access, or enlarge the RIN table.


C__1565
C-
61   OUT OF GROUP DISC SPACE (FSERR 61):

     The program tried to allocate more disc space than is allowed for a given
     group; e.g.  it tried to build a 10,000-sector file in a group which
     already had 95,000 sectors and was limited to 100,000 sectors.

     WORKAROUND: Decrease the amount of disc space used by files in that group
     (by purging or squeezing files) or ask the account manager to increase the
     group disc space limit.


C__1566
C-
62   OUT OF ACCOUNT DISC SPACE (FSERR 62):

     The program tried to allocate more disc space than is permitted for the
     account in which it tried to allocate it.

     WORKAROUND: Decrease the amount of disc space used by files in that
     account (by purging or squeezing files) or ask the system manager to
     increase the account disc space limit.


C__1567
C-
64   USER LACKS MULTI-RIN CAPABILITY (FSERR 64):

     The program was not :PREPed with MR (Multi-Rin) capability, yet tried to
     lock a file when another file (or RIN) was already locked by that program.

     WORKAROUND: :PREP the program with MR capability or do not try to lock a
     file when you have already locked another one.


C__1568
C-
65   PUNCH HOPPER EMPTY (FSERR 65):


C__1569
C-
66   PLOTTER LIMIT SWITCH REACHED (FSERR 66):


C__1570
C-
67   PAPER TAPE ERROR (FSERR 67):


C__1571
C-
68   INSUFFICIENT SYSTEM RESOURCES (FSERR 68):


C__1572
C-
69   I/O ERROR (FSERR 69):


C__1573
C-
70   I/O ERROR WHILE PRINTING HEADER/TRAILER (FSERR 70):


C__1574
C-
71   TOO MANY FILES OPEN (FSERR 71):

     The program attempted to open a file, but there was not enough room in the
     system area (PCBX) of the program's stack for the information for that
     file.

     WORKAROUND: Close some files which are no longer necessary before trying
     the open, or run the program with the ;NOCB keyword in the :RUN command.


C__1575
C-
72   INVALID FILE NUMBER (FSERR 72):

     An attempt was made to access (e.g.  read or write) a file that had not
     been opened or that is a privileged file; for instance, a read was
     requested against file number 10, but no file file number 10 was open.

     WORKAROUND: Correct your program or enter privileged mode before trying to
     access the file (if the file is privileged).


C__1576
C-
73   BOUNDS VIOLATION (FSERR 73):

     You are attempting to read or write more data than could fit into your I/O
     buffer (e.g.  you are trying to read 100 words into an 80-word array).

     WORKAROUND:  Decrease the length of the data you are trying to read or
     write or enlarge your program's I/O buffer.


C__1577
C-
74   NO ROOM LEFT IN STACK SEGMENT FOR ANOTHER FILE ENTRY (FSERR 74):

     When trying to do an FOPEN, the file system tried to expand your stack
     data segment to have room for the information on the file being opened;
     this caused an error because it would make the data segment too large.

     WORKAROUND: Often, this does not mean that you were using too much stack
     space AT THE TIME OF THE FOPEN.  Rather, you might have used a lot of
     stack space earlier, and that space was not deallocated (since your stack
     data segment is never automatically shrunk by the system).  If you call
     "ZSIZE (0)" (to shrink the stack data segment to only the amount you're
     currently using) immediately before the FOPEN call, the problem may very
     well go away.  If it doesn't, you might consider using less stack space or
     running your program with ;NOCB.


C__1578
C-
77   NO-WAIT I/O PENDING (FSERR 77):


C__1579
C-
78   NO NO-WAIT I/O PENDING FOR ANY FILE (FSERR 78):


C__1580
C-
79   NO NO-WAIT I/O PENDING FOR SPECIAL FILE (FSERR 79):


C__1581
C-
80   SPOOFLE SIZE EXCEEDS CONFIGURATION (FSERR 80):


C__1582
C-
81   NO "SPOOL" CLASS IN SYSTEM (FSERR 82):


C__1583
C-
82   INSUFFICIENT SPACE FOR SPOOFLE (FSERR 82):


C__1584
C-
83   I/O ERROR ON SPOOFLE (FSERR 83):


C__1585
C-
84   DEVICE UNAVAILABLE FOR SPOOFLE (FSERR 84):


C__1586
C-
85   OPERATION INCONSISTENT WITH SPOOLING (FSERR 85):


C__1587
C-
86   SPOOLING INTERNAL ERROR (FSERR 86):


C__1588
C-
87   BAD SPOOFLE BLOCK (FSERR 87):


C__1589
C-
88   NONEXISTENT SPOOFLE (FSERR 88):


C__1590
C-
89   POWER FAILURE (FSERR 89):


C__1591
C-
90   EXCLUSIVE VIOLATION: FILE BEING ACCESSED (FSERR 90):

     Exclusive access was requested to a file which is already being accessed;
     thus, exclusive access cannot be granted.

     WORKAROUND: Specify SHR (shared) or EAR (exclusive - allow read) access
     when opening the file or wait for the accessor to close the file.


C__1592
C-
91   EXCLUSIVE VIOLATION: FILE BEING ACCESSED EXCLUSIVELY (FSERR 91):

     Access was requested to a file which is being accessed exclusively by some
     other user.

     WORKAROUND: Wait for the accessor to close the file.


C__1593
C-
92   LOCKWORD VIOLATION (FSERR 92):

     An invalid lockword was specified at file open time or when the file
     system prompted the user for a lockword.

     WORKAROUND: Specify a correct lockword or remove or change the lockword on
     the disc file.


C__1594
C-
93   SECURITY VIOLATION (FSERR 93):

     Permitting the user to access this file in the specified access mode would
     be a breach of file security.

     WORKAROUND: Change the access mode specified in the program to one which
     is permitted or ask the file's creator to :RELEASE or :ALTSEC the file.


C__1595
C-
94   USER IS NOT CREATOR (FSERR 94):

     An attempt was made to :RENAME or FRENAME a file by someone other than the
     file's creator.

     WORKAROUND: Do not perform the :RENAME or FRENAME, ask the creator of the
     file to do the :RENAME, or (if you have read and write access to the file
     and are a user of MPEX) use MPEX's %RENAME command.


C__1596
C-
95   READ COMPLETED DUE TO BREAK (FSERR 95):


C__1597
C-
96   DISC I/O ERROR (FSERR 96):

     Hardware failure.  Call your CE.


C__1598
C-
97   NO CONTROL Y PIN (FSERR 97):


C__1599
C-
98   READ TIME OVERFLOW (FSERR 98):


C__1600
C-
99   BOT AND BACKSPACE TAPE (FSERR 99):


C__1601
C-
100  DUPLICATE PERMANENT FILE NAME (FSERR 100):

     The program tried to save (close with SAVE disposition) a new or temporary
     file as a permanent file, but a permanent file with that name already
     exists.

     WORKAROUND: Purge the other file with that name.


C__1602
C-
101  DUPLICATE TEMPORARY FILE NAME (FSERR 101):

     The program tried to save as a temporary file (close with TEMP
     disposition) a new file, but a temporary file with that name already
     exists.

     WORKAROUND: Purge the other temporary file with that name.


C__1603
C-
102  DIRECTORY I/O ERROR (FSERR 102):

     The directory (or part of it) is clobbered.  You're in big trouble.

     WORKAROUND: None.


C__1604
C-
103  PERMANENT FILE DIRECTORY OVERFLOW (FSERR 103):

     There is no more room in the system file directory for this file (the
     system file directory typically allows approximately 1,200 files per
     group).

     WORKAROUND: Purge some of the files in the group in which you wish to
     build the file.


C__1605
C-
104  TEMPORARY FILE DIRECTORY OVERFLOW (FSERR 104):

     There is no more room in your job / session temporary file directory for
     this file.

     WORKAROUND: Purge some temporary files or :RESET some :FILE equations or
     :CRESET some :CLINE equations.


C__1606
C-
105  BAD VARIABLE BLOCK STRUCTURE (FSERR 105):

     The variable record length file being accessed has an inconsistent
     structure, or would have an inconsistent structure if this access were to
     go through (if you are writing NOBUF).

     WORKAROUND: If you are writing NOBUF, correct your program; otherwise,
     none.


C__1607
C-
106  EXTENT SIZE EXCEEDS MAXIMUM (FSERR 106):

     The program attempted to build a file which would have extents larger than
     65,534 sectors, the maximum permitted.

     WORKAROUND: Increase the number of extents in the file or decrease the
     extent size by decreasing the record size or file limit of the file.


C__1608
C-
107  INSUFFICIENT SPACE FOR USER LABELS (FSERR 107):

     The maximum number of user labels for a file is 254.

     WORKAROUND: Decrease the number of user labels requested by the program.


C__1609
C-
108  INVALID FILE LABEL (FSERR 108):

     The file is inaccessible because the file is invalid (probably destroyed -
     and unrecoverable).

     WORKAROUND: None.


C__1610
C-
109  INVALID CARRIAGE CONTROL (FSERR 109):

     The program tried to do a write with a CCTL code of 1 (embedded CCTL) but
     with a buffer length of 0; or, the program attempted an FCONTROL mode 1
     (transfer CCTL code) with a parameter of 1.

     WORKAROUND: Correct the program.


C__1611
C-
110  ATTEMPT TO SAVE PERMANENT FILE AS TEMPORARY (FSERR 110):

     An attempt was made to close a permanent file with temporary (TEMP)
     disposition: this is illegal.

     WORKAROUND: Correct the program.


C__1612
C-
111  USER LACKS SAVE FILES (SF) CAPABILITY (FSERR 111):


C__1613
C-
112  USER LACKS PRIVATE VOLUMES (UV) CAPABILITY (FSERR 112):


C__1614
C-
113  VOLUME SET NOT MOUNTED - MOUNT PROBLEM (FSERR 113):


C__1615
C-
114  VOLUME SET NOT DISMOUNTED - DISMOUNT PROBLEM (FSERR 114):


C__1616
C-
115  ATTEMPTED RENAME ACROSS VOLUME SETS - REJECTED (FSERR 115):


C__1617
C-
116  INVALID TAPE LABEL FOPEN PARAMETERS  (FSERR 116):


C__1618
C-
117  ATTEMPED TO WRITE ON AN UNEXPIRED TAPE FILE  (FSERR 117):


C__1619
C-
118  INVALID HEADER OR TRAILER TAPE LABEL  (FSERR 118):


C__1620
C-
119  I/O ERROR POSITIONING TAPE FOR TAPE LABELS  (FSERR 119):


C__1621
C-
120  ATTEMPT TO WRITE IBM STANDARD TAPE LABEL  (FSERR 120):


C__1622
C-
121  TAPE LABEL LOCKWORD VIOLATION  (FSERR 121):


C__1623
C-
122  TAPE LABEL TABLE OVERFLOW (FSERR 122):


C__1624
C-
123  END OF TAPE VOLUME SET  (FSERR 123):


C__1625
C-
124  ATTEMPTED TO APPEND LABELED TAPE  (FSERR 124):


C__1626
C-
125  EXPIRATION DATE CAN'T BE LATER THAN PRECEDING FILE'S (FSERR 125):


C__1627
C-
126  CHARACTER SET NUMBER MUST BE BETWEEN 0 AND 31.  (FSERR 126):


C__1628
C-
127  FORM NUMBER MUST BE BETWEEN 0 AND 31.  (FSERR 127):


C__1629
C-
128  LOGICAL PAGE NUMBER MUST BE BETWEEN 0 AND 31.  (FSERR 128):


C__1630
C-
129  VERTICAL FORMAT NUMBER MUST BE BETWEEN 0 AND 31.  (FSERR 129):


C__1631
C-
130  NUMBER OF COPIES MUST BE BETWEEN 1 AND 32767.  (FSERR 130):


C__1632
C-
131  NUMBER OF OVERLAYS MUST BE BETWEEN 1 AND 8.  (FSERR 131):


C__1633
C-
132  PAGE LENGTH PARM MUST BE BETWEEN 12 (=3") AND 68 (=17").  (FSERR 132):


C__1634
C-
133  PICTURE NUMBER MUST BE BETWEEN 0 AND 31.  (FSERR 133):


C__1635
C-
134  EXTENDED CAPABILITY PARM MUST BE 0 (OFF) OR 1 (ON).  (FSERR 134):


C__1636
C-
135  UNRECOVERED MEDIA ERROR.  (FSERR 135):


C__1637
C-
136  USER LIMIT EXCEEDED.  (FSERR 136):


C__1638
C-
137  DEFECTIVE TRACK ON FOREIGN DISC  (FSERR 137):


C__1639
C-
138  TRACK DOES NOT EXIST ON FOREIGN DISC  (FSERR 138):


C__1640
C-
139  DELETED RECORD ON IBM DISKETTE  (FSERR 139):


C__1641
C-
140  ACCESS DENIED DUE TO CORRUPT ACD,FILE OWNER MUST REAPPLY ACD (FSERR 14 0):


C__1642
C-
148  INACTIVE RIO RECORD (FSERR 148):

     An FPOINT, FREADDIR, or FSPACE positioned the record pointer at an
     inactive record in an RIO (Relative I/O) file.

     WORKAROUND: None necessary.


C__1643
C-
149  MISSING ITEM NUMBER OR RETURN-VARIABLE (FSERR 148):

     An item number was specified without a corresponding variable or vice
     versa in an FFILEINFO intrinsic call.

     WORKAROUND: Correct the program.


C__1644
C-
150  INVALID ITEM NUMBER (FSERR 150):

     An item number specified in an FFILEINFO intrinsic call is invalid.

     WORKAROUND: Correct the program.


C__1645
C-
151  CURRENT RECORD WAS LAST RECORD WRITTEN BEFORE SYSTEM CRASHED (FSERR 151):


C__1646
C-
152  UNRECOGNIZED KEYWORD IN FOPEN DEVICE PARAMETER (FSERR 152):


C__1647
C-
153  EXPECTED ";" OR CARRIAGE RETURN IN DEVICE PARAMETER (FSERR 153):


C__1648
C-
154  ENVIRONMENT FILE OPEN ERROR (FSERR 154):


C__1649
C-
155  NOT ENVIRONMENT FILE.CHECK FILE CODE OR RECORD SIZE.  (FSERR 155):


C__1650
C-
156  ENVIRONMENT HEADER RECORD INCORRECT (FSERR 156):


C__1651
C-
157  UNCOMPILED ENVIRONMENT FILE (FSERR 157):


C__1652
C-
158  ERROR READING ENVIRONMENT FILE (FSERR 158):


C__1653
C-
159  ERROR CLOSING ENVIRONMENT FILE (FSERR 159):


C__1654
C-
160  ERROR DOING FDEVICECONTROL FROM ENVIRONMENT FILE (FSERR 160):


C__1655
C-
161  TOO MANY PARAMETERS IN DEVICE STING - OVERFLOW (FSERR 161):


C__1656
C-
162  EXPECTED "=" AFTER KEYWORD IN DEVICE PARAMETER (FSERR 162):


C__1657
C-
163  "ENV" BACK REFERENCE IN FILE EQUATION INCORRECT (FSERR 163):


C__1658
C-
164  DEVICE PARAMETER TOO LARGE OR MISSING CARRIAGE RETURN (FSERR 164):


C__1659
C-
165  INVALID DENSITY SPECIFICATION (FSERR 165):


C__1660
C-
166  FFILEINFO FAILED IN ACCESSING REMOTE SPOOL FILE.  (FSERR 166):


C__1661
C-
167  SPOOL FILE LABEL ERROR, CAN'T INSERT INV FILE NAME.  (FSERR 167):


C__1662
C-
168  ITEM NOT SUPPORTED ON REMOTE SYSTEM.  (FSERR 168):


C__1663
C-
170  RECORD IS MARKED FOR DELETION  (FSERR 170):


C__1664
C-
171  DUPLICATE KEY VALUE  (FSERR 171):


C__1665
C-
172  NO SUCH KEY  (FSERR 172):


C__1666
C-
173  TCOUNT PARAMETER LARGER THAN RECORD SIZE  (FSERR 173):


C__1667
C-
174  CAN NOT GET EXTRA DATA SEGMENT  (FSERR 174):


C__1668
C-
175  KSAM INTERNAL ERROR (FSERR 175):


C__1669
C-
176  ILLEGAL EXTRA DATA SEGMENT LENGTH (FSERR 176):


C__1670
C-
177  TOO MANY EXTRA DATA SEGMENTS FOR THIS PROCESS  (FSERR 177):


C__1671
C-
178  NOT ENOUGH VIRTUAL MEMORY FOR EXTRA DATA SEGMENT  (FSERR 178):


C__1672
C-
179  THE FILE MUST BE LOCKED BEFORE ISSUING THIS INTRINSIC  (FSERR 179):


C__1673
C-
180  KSAM FILE MUST BE REBUILT  (FSERR 180):


C__1674
C-
181  INVALID KEY STARTING POSITION  (FSERR 181):


C__1675
C-
182  FILE IS EMPTY  (FSERR 182):


C__1676
C-
183  RECORD DOES NOT CONTAIN ALL KEYS  (FSERR 183):


C__1677
C-
184  INVALID RECORD NUMBER (FFINDN INTRINSIC)  (FSERR 184):


C__1678
C-
185  SEQUENCE ERROR IN PRIMARY KEY  (FSERR 185):


C__1679
C-
186  INVALID KEY LENGTH  (FSERR 186):


C__1680
C-
187  INVALID KEY SPECIFICATION  (FSERR 187):


C__1681
C-
188  INVALID DEVICE SPECIFICATION  (FSERR 188):


C__1682
C-
189  INVALID RECORD FORMAT  (FSERR 189):


C__1683
C-
190  INVALID KEY BLOCKING FACTOR VALUE  (FSERR 190):


C__1684
C-
191  RECORD DOES NOT CONTAIN SEARCH KEY SPECIFIED FOR DELETION (FSERR 191):


C__1685
C-
192  SYSTEM FAILURE OCCURRED WHILE THE KSAM FILE WAS OPENED (FSERR 192):


C__1686
C-
193  $STDIN/$STDLIST CANNOT BE REDIRECTED TO KSAM FILES  (FSERR 193):


C__1687
C-
194  KSAM FILES NOT ALLOWED FOR GLOBAL AFT'S  (FSERR 194):


C__1688
C-
195  GLOBAL FILES CANNOT BE REMOTE FILES  (FSERR 195):


C__1689
C-
196  LANGUAGE NOT SUPPORTED  (FSERR 196):


C__1690
C-
197  NATIVE LANGUAGE INTERNAL ERROR (FSERR 197):


C__1691
C-
198  INVALID VERSION NUMBER IN KSAM FILE  (FSERR 198):


C__1692
C-
199  UNABLE TO SWITCH THE LOCKING MODE (FSERR 199):


C__1693
C-
201  REMOTE DID NOT RESPOND WITH THE CORRECT REMOTE ID.  (DSERR 201):


C__1694
C-
202  SPECIFIED PHONE NUMBER IS INVALID (DSERR 202):


C__1695
C-
203  REMOTE ABORT/RESUME NOT VALID WHEN DOING PROGRAM-TO-PROGRAM COMMUNICATION.
     USE LOCAL ABORT/RESUME.  (DSWARN 203):


C__1696
C-
204  UNABLE TO ALLOCATE AN EXTRA DATA SEGMENT FOR DS/3000.  (DSERR 204):


C__1697
C-
205  UNABLE TO EXPAND THE DS/3000 EXTRA DATA SEGMENT.  (DSERR 205):


C__1698
C-
206  SLAVE PTOP FUNCTION ISSUED FROM A MASTER PROGRAM.  (DSERR 206):


C__1699
C-
207  SLAVE PTOP FUNCTION OUT OF SEQUENCE.  (DSERR 207):


C__1700
C-
208  MASTER PTOP FUNCTION ISSUED BY A SLAVE PROGRAM.  (DSERR 208):


C__1701
C-
209  SLAVE PROGRAM DOES NOT EXIST OR IS NOT PROGRAM FILE.  (DSERR 209):


C__1702
C-
210  WARNING -- INVALID MAXDATA OR DLSIZE FOR A SLAVE PROGRAM.  SYSTEM DEFAULTS
     ARE IN EFFECT.  (DSWARN 210):


C__1703
C-
211  SLAVE ISSUED A REJECT TO A MASTER PTOP OPERATION.  (DSWARN 211):


C__1704
C-
212  FILE NUMBER FROM IOWAIT NOT A DS LINE NUMBER.  (DSWARN 212):


C__1705
C-
213  EXCLUSIVE USE OF A DS LINE REQUIRES BOTH ND AND CS CAPABILITY.  (DSERR
     213):


C__1706
C-
214  DS LINE WAS NOT OPENED WITH A USER :DSLINE COMMAND.  (DSERR 214):


C__1707
C-
215  DSLINE CANNOT BE ISSUED BACK TO THE MASTER COMPUTER.  (DSERR 215):


C__1708
C-
216  MESSAGE REJECTED BY THE REMOTE COMPUTER.  (DSERR 216):


C__1709
C-
217  INSUFFICIENT AMOUNT OF USER STACK AVAILABLE.  (DSERR 217):


C__1710
C-
218  INVALID PTOP FUNCTION REQUESTED.  (DSERR 218):


C__1711
C-
219  MULTIPLE POPEN.  ONLY ONE MASTER PTOP OPERATION CAN BE ACTIVE ON A DS
     LINE.  (DSERR 219):


C__1712
C-
220  PROGRAM EXECUTING GET WAS NOT CREATED BY POPEN.  (DSERR 220):


C__1713
C-
221  INVALID DS MESSAGE FORMAT.  INTERNAL DS ERROR.  (DSERR 221):


C__1714
C-
222  MASTER PTOP FUNCTION ISSUED PRIOR TO A POPEN.  (DSERR 222):


C__1715
C-
223  REQUEST TO SEND MORE DATA THAN SPECIFIED IN POPEN (DSERR 223):


C__1716
C-
224  FILE EQUATIONS FOR A REMOTE FILE CONSTITUTE A LOOP.  (DSERR 224):


C__1717
C-
225  CANNOT ISSUE POPEN TO A SLAVE SESSION IN BREAK MODE.  (DSERR 225):


C__1718
C-
226  SLAVE PROGRAM HAS TERMINATED BEFORE EXECUTING "GET".  (DSERR 226):


C__1719
C-
227  RFA/RDBA COULD NOT FIND OR CREATE A REMOTE SESSION.  (DSERR 227):


C__1720
C-
228  EXCEEDED MAXIMUM NUMBER OF VIRTUAL CHANNELS PER JOB.  (DSERR 228):


C__1721
C-
229  TOO MANY DS USERS ON THIS SYSTEM.  CANNOT OBTAIN A VIRTUAL PROCESS NUMBER.
     (DSERR 229):


C__1722
C-
230   (DSERR 230):


C__1723
C-
231  INVALID FACILITY IN CONNECTION REQUEST.  (DSERR 231):


C__1724
C-
232  THE REMOTE COMPUTER IS NOT OBTAINABLE.  (DSERR 232):


C__1725
C-
233  VIRTUAL CIRCUIT IS NOT AVAILABLE.  (DSERR 233):


C__1726
C-
234  QUEUEING IS REQUIRED TO COMPLETE THE REQUEST.  (DSERR 234):


C__1727
C-
235  DS MESSAGE SEQUENCING ERROR.  (DSERR 235):


C__1728
C-
236  COMMUNICATIONS HARDWARE HAS DETECTED AN ERROR.  (DSERR 236):


C__1729
C-
237  CANNOT CURRENTLY GAIN ACCESS TO THE TRACE FILE.  (DSERR 237):


C__1730
C-
238  COMMUNICATIONS INTERFACE ERROR.  INTERNAL FAILURE.  (DSERR 238):


C__1731
C-
239  COMMUNICATIONS INTERFACE ERROR.  TRACE MALFUNCTION.  (DSERR 239):


C__1732
C-
240  LOCAL COMMUNICATION LINE WAS NOT OPENED BY OPERATOR.  (DSERR 240):


C__1733
C-
241  DS LINE IN USE EXCLUSIVELY OR BY ANOTHER SUBSYSTEM (DSERR 241):


C__1734
C-
242  INTERNAL DS SOFTWARE ERROR ENCOUNTERED.  (DSERR 242):


C__1735
C-
243  REMOTE OR PDN IS NOT RESPONDING.  (DSERR 243):


C__1736
C-
244  COMMUNICATIONS INTERFACE ERROR.  LINE RESET OCCURRED.  (DSERR 244):


C__1737
C-
245  COMMUNICATIONS INTERFACE ERROR.  RECEIVE TIMEOUT.  (DSERR 245):


C__1738
C-
246  COMMUNICATIONS INTERFACE ERROR.  REMOTE DISCONNECTED.  (DSERR 246):


C__1739
C-
247  COMMUNICATIONS INTERFACE ERROR.  LOCAL TIME OUT.  (DSERR 247):


C__1740
C-
248  COMMUNICATIONS INTERFACE ERROR.  CONNECT TIME OUT.  (DSERR 248):


C__1741
C-
249  COMMUNICATIONS INTERFACE ERROR.  REMOTE REJECTED CONNECTION.  (DSERR 249):


C__1742
C-
250  COMMUNICATIONS INTERFACE ERROR.  CARRIER LOST.  (DSERR 250):


C__1743
C-
251  COMMUNICATIONS INTERFACE ERROR.  LOCAL DATA SET FOR THE DS LINE WENT NOT
     READY.  (DSERR 251):


C__1744
C-
252  COMMUNICATIONS INTERFACE ERROR.  HARDWARE FAILURE.  (DSERR 252):


C__1745
C-
253  COMMUNICATIONS INTERFACE ERROR.  NEGATIVE RESPONSE TO THE DIAL REQUEST BY
     THE OPERATOR.  (DSERR 253):


C__1746
C-
254  COMMUNICATIONS INTERFACE ERROR.  INVALID I/O CONFIGURATION.  (DSERR 254):


C__1747
C-
255  COMMUNICATIONS INTERFACE ERROR.  UNANTICIPATED CONDITION.  (DSERR 255):


C__1748
C-
257  DATA TRANSFER COUNT TOO LARGE.  (DSERR 257):


C__1749
C-
300  NO.  OF OPENS FOR FILE EXCEEDS 255 (FSERR 300):


C__1750
C-
301  FREE SPACE TABLE FOR LDEV ! IS FULL, RUN VINIT -COND (FSERR 301):


C__1751
C-
302  INVALID ITEM NUMBER FOR FDEVICECONTROL  (FSERR 302):


C__1752
C-
303  INVALID ACCESS FOR ITEM NUMBER TO FDEVICECONTROL  (FSERR 303):


C__1753
C-
304  ATTEMPT TO CHANGE TERMINAL PARITY IN 8 BIT MODE (FSERR 304):


C__1754
C-
305  INVALID FORMAT IN TERMINAL CONFIGURATION FILE (FSERR 305):


C__1755
C-
306  CHECKSUM ERROR IN TERMINAL CONFIGURATION FILE (FSERR 306):


C__1756
C-
307  PASSED VALUE TO FDEVICECONTROL LESS THAN MIN (FSERR 307):


C__1757
C-
308  PASSED VALUE TO FDEVICECONTROL IS UNSUPPORTED  (FSERR 308):


C__1758
C-
309  PASSED VALUE TO FDEVICECONTROL IS UNSUPPORTED  (FSERR 309):


C__1759
C-
310  COUNT TO FDEVICECONTROL INSUFFICIENT TO RETURN INFO (FSERR 310):


C__1760
C-
311  COUNT TO FDEVCNT GREATER THAN AVAILABLE TO STORE INFO (FSERR 311):


C__1761
C-
312  PASSED SPECIAL CHARACTER HAS PREVIOUSLY DEFINED FUNCTION (FSERR 312):


C__1762
C-
350  KSAM LOCK TABLE FULL (FSERR 350):


C__1763
C-
351  TOO MANY RECORD LOCKS IN ONE PROCESS (FSERR 351):


C__1764
C-
352  RECORD WAS LOCKED ALREADY (FSERR 352):


C__1765
C-
353  FILE MUST BE UNLOCKED BEFORE ISSUING THIS INTRINSIC (FSERR 353):


C__1766
C-
354  DATA INTEGRITY VIOLATION (FSERR 354):


C__1767
C-
355  FILE IS LOCKED BY ANOTHER PROCESS (FSERR 355):


C__1768
C-
356  LOCK REQUEST REJECTED DUE TO POTENTIAL DEADLOCK (FSERR 356):


C__1769
C-
357  DATA MAY BE INVALID BECAUSE FILE IS LOCKED BY OTHERS (FSERR 357):

                         *** END OF MPEX DOCUMENT ***