The MAINUSER subprogram is an Application Programming Interface, which allows you to perform SYSMAIN utility functions from any user-written object (subroutine, program or subprogram) as an alternative to using SYSMAIN utility menus. Upon completion of the SYSMAIN function, the utility is terminated and control is returned to the object from which the request was issued. MAINUSER can be used in either online or batch mode. An example of a callable routine is the MAINCALL program, which is supplied in the SYSMAIN system library.
This section provides instructions for using MAINUSER and the syntax that applies when specifying commands for executing SYSMAIN utility functions.
To invoke and execute MAINUSER
Issue a CALLNAT statement that contains the following
syntax elements:
CALLNAT 'MAINUSER' command error message
library
where the variable values denote the following parameters:
| Parameter | Natural Data Format/Length | Explanation |
|---|---|---|
| command | A250 | The command string to be executed by SYSMAIN: see Using Commands. |
| error | N4 | The return code issued by SYSMAIN at the end of processing to indicate a normal end of processing or an error. |
| message | A72 | The message corresponding to the error given online. |
| library | A8 | The name of the library containing the utility SYSMAIN; by default, this is the library SYSMAIN. (This parameter is provided for compatibility reasons only.) |
SYSMAIN functions can be executed using commands issued as a parameter of the MAINUSER subprogram.
A command consists of keywords and variable values. For each SYSMAIN function to be performed, the keywords and variable values are shown in the corresponding syntax diagrams below and explained in the section Keywords and Variables in Commands. The symbols in the syntax diagrams correspond to the syntax symbols used for system commands. These symbols are explained in System Command Syntax in the System Commands documentation.
The sequence of the command syntax is not completely fixed. The following rules apply:
SYSMAIN function, object type and object name must be the first three parameters of the command string.
A period (.) indicates the end of a command. If this character is detected anywhere within a command string, all subsequent data is ignored.
In the syntax diagrams, FM or IN is shown
instead of the FROM keyword to make the diagrams easier to read;
however, FROM can always be used as a synonym for FM
or IN and vice versa.
The syntax of the where-clause and the with-clause is identical for each command.
The following command syntax applies to the find and list functions:
|
|
|
|
|
|
name |
|
IN
[LIBRARY]
lib-name |
|
[where-clause] [with-clause] |
LIST VIEW * IN TESTLIB
L SAVED TEST* IN TESTLIB TYPE PNS FNR 6
L SA TEST* IN TESTLIB FNR 6 DBID 2 TYPE PM FMDATE 2007-01-01
FIND PROG1 IN * DBID 1 FNR 6
F STOWED MAINMENU IN SYS* WHERE DBID 1 FNR 5
FIND ALL PROG2 IN PROD* FNR 27 DBID 1
The following command syntax applies to the copy and move functions:
|
|
|
|
|
|
||||||
| name |
|
FM [LIBRARY]
lib-name
|
|
[where-clause] | ||||||
TO
[LIBRARY]
lib-name |
[where-clause] [with-clause] | |||||||||
COPY PROG1 FM TESTORD TO ORDERS DBID 1 FNR 6 REP
C PGM* FM TESTLIB TO PRODLIB WITH REP TYPE PNS
C VIEW PERS FM OLDLIB FNR 10 TO NEWLIB FNR 16 REPLACE
MOVE VIEW PERSONNEL FM OLDLIB FNR 20 TO NEWLIB FNR 24
M PROG1 TO NEWLIB
M STOWED * FM OLDLIB TO NEWLIB WHERE DBID 100 FNR 160 WITH XREF Y
The following command syntax applies to the delete function:
DELETE
|
|
|
name |
|
IN [LIBRARY]
lib-name
|
|
[where-clause] [with-clause] |
DELETE SA * IN LIBTEST TYPE GLA
D * IN TESTORD TYPE PM
D VIEW FINANCE IN TESTLIB DBID 12 FNR 27
The following command syntax applies to the rename function:
RENAME
|
|
|
|
| name | AS new-name
[with-clause]
|
||
FM
[LIBRARY]
lib-name [where-clause]
|
|||
TO [LIBRARY]
lib-name [where-clause]
|
RENAME PGM1 AS PROG1
R PGM1 AS PROG1 FM TESTLIB DBID 1 FNR 5 TO PRODLIB DBID 2 FNR 6
The following command syntax applies to the import function:
IMPORT
|
|
|
|
| name | FM
[PATH]
path-name |
||
TO [LIBRARY]
lib-name [where-clause]
[with-clause]
|
IMPORT ALL PGM* FM D:\NAT-PROGRAMS TO IMP-LIB
I RES res1.bmp FM D:\RESOURCES TO IMP-LIB
[WHERE] [DBID
dbid] [FNR
fnr]
|
|
[DIC
(dbid,fnr,password,cipher)]
|
|
[SEC
(dbid,fnr,password,cipher)]
|
|
Commas must be used as separators between the values following the
DIC and SEC keywords, or if a value is missing. For
example: DIC (10,,secret,2a). If the ID
session parameter (see also ID - Input
Delimiter Character in the Parameter
Reference documentation) has been set to a comma, use a slash (/) as
the separator between values.
[WITH]
|
[TYPE
type] [FMDATE date]
[FMTIME time]
|
||||||||
[USER user-id]
|
|
XREF
|
|
|
|
|
|||
[REPLACE] [RCOP] [NOPROMPT] [HELP]
|
|||||||||
|
|
|
||||||||
This section explains the keywords and corresponding variable values (if required) used in a command.
Keywords are listed alphabetically. Letters in italics represent variable values that must be supplied with a keyword. For each variable value, the Natural data format and length is indicated.
| Keyword | Value |
Natural Data |
Explanation | ||||
|---|---|---|---|---|---|---|---|
ALL
|
name | A9 | Only applies to programming objects.
The name of the object to be processed or a range of names; see Specifying a Range of Names. Any saved (source) objects and/or cataloged objects are processed. |
||||
CATALOGED
|
name | A9 | Only applies to programming objects.
The name of the cataloged object to be processed or a range of names; see Specifying a Range of Names. |
||||
SAVED
|
name | A9 | Only applies to programming objects.
The name of the saved (source) object to be processed or a range of names; see Specifying a Range of Names. |
||||
STOWED
|
name | A9 | Only applies to programming objects.
The name of an object (or a range of names) for which the saved (source) and the cataloged object are to be processed (see also Specifying a Range of Names). Only an object that exists as both a saved (source) object and a cataloged object is processed. The exceptions to this are copycode and text, neither of which can be cataloged. However, they are included in processing when this option is specified. |
||||
VIEW
|
name | A32 | Only applies to DDMs (data definition modules).
The name of the DDM to be processed or a range of names; see Specifying a Range of Names. |
||||
RESOURCE
|
name | A255 | Only applies to shared resources.
The name of the shared resource to be processed or a range of names; see Specifying a Range of Names. |
||||
|
lib-name |
A8 |
Specifies a source library or a source path.
The source library or path contains the object to be processed. |
|||||
TO
|
lib-name | A8 | Specifies a target library. | ||||
AS
|
new-name |
A8 |
The new name to be given to an object when it is renamed with
the RENAME command. Format/length A8 applies to
programming objects, A32 to DDMs and A255 to shared resources.
|
||||
LIBRARY
|
lib-name | A8 | An optional keyword that indicates the name
(lib-name) of a source or a target library. If you
omit the keyword and respective value, the library where you logged on before
you invoked SYSMAIN is used for processing.
The source library contains the object to be processed. The target library is the library to which the object is to be copied or moved, or where the object is renamed. lib-name must be specified immediately
after the |
||||
PATH
|
path-name | A253 | Only applies to the IMPORT command.
An optional keyword that indicates the name (path-name) of a source path. path-name must be specified immediately
after the |
||||
WHERE
|
where-clause | - | An optional keyword that indicates the start of a
where-clause.
The where-clause must always follow the
|
||||
DBID
|
dbid | N5 | The database ID (DBID) of a source or a target system file.
The source system file contains the object to be processed. The target system file is the system file to which the object is to be copied or moved, or where the object is renamed if relevant. Valid DBIDs are
If no DBID or FNR (file number) is specified,
the following applies: See also the section File Security in Remote Environments. |
||||
FNR
|
fnr | N5 | The file number (FNR) of a source or a target system file.
The source system file contains the object to be processed. The target system file is the system file to which the object is to be copied or moved, or where the object is renamed if relevant. Valid FNRs are
If no See also the section File Security in Remote Environments. |
||||
DIC
|
dbid |
A80 | Specifies the environment of the FDIC source and/or target
system file: database ID (dbid),
file number (fnr),
Adabas password (password) and Adabas cipher code
(cipher).
See also the section File Security in Remote Environments. |
||||
SEC
|
dbid |
A80 | Specifies the environment of the FSEC source and/or target
system file: database ID (dbid),
file number (fnr),
Adabas password (password) and Adabas cipher code
(cipher).
See also the section File Security in Remote Environments. |
||||
WITH
|
with-clause | - | An optional keyword that indicates the start of a
with-clause.
The keywords and values of the with-clause can be specified in any order, and the with-clause can be placed in any location within the command string, except in the first three positions. |
||||
TYPE
|
type | A20 | The type(s) of object to be processed as listed in TYPE Specification below. | ||||
FMDATE
|
date | A10 |
The start date of a time period: A date must be specified in a valid Natural date format. The
default format is the international format
YYYY-MM-DD
(YYYY = year, MM = month,
DD = day), for example, |
||||
FMTIME
|
time | A5 | Only applies if FMDATE
is specified.
Specifies a start time: A time must be specified in the format
HH:II
(HH = hours, II =
minutes), for example, |
||||
USER
|
user-id | A8 |
A user ID: |
||||
XREF
|
|
A1 | Only applies to programming objects and if Predict is
installed.
Indicates whether XRef data stored in Predict system files is to be processed. You can specify one of the following values:
See also the section XRef Considerations. |
||||
REPLACE
|
- | - | Activates the replace option used in a
with-clause.
An object with the same name in the target environment is replaced by the object to be processed. Note: |
||||
RCOP
|
- | - | Specifies that a copy of the object being renamed is to be made. | ||||
NOPROMPT
|
- | - | Not applicable in batch mode.
Disables ( |
||||
HELP
|
- | - | This keyword is provided for compatibility reasons only. | ||||
Only applies to the IMPORT command.
Indicates structured mode described in Natural Programming Modes in the Programming Guide. |
|||||||
REPORT
|
Only applies to the IMPORT command.
Indicates reporting mode described in Natural Programming Modes in the Programming Guide. |
||||||
.
|
- | - | A period (.) indicates the end of a command. If this character is detected anywhere within a command string, all subsequent data is ignored. |
The following table lists all valid object-type codes for programming
objects that can be used with the TYPE keyword:
All SYSMAIN functions provide the option to specify either a name or a range of names for the libraries or the objects to be selected.
The valid asterisk (*) notations for name ranges are listed below where value denotes any combination of one or more characters:
| Input | Objects or Libraries Selected |
|---|---|
| * | All objects or libraries. |
| value* | All objects or libraries with names that start with
value.
Example: |
| value*value* | All objects or libraries that match
value combined with one or two asterisks (*) in any
order.
Example: |
