The utility SYSEXT is used to locate and test Natural Application Programming Interfaces (APIs) contained in the current system library SYSEXT.
A Natural API is a Natural subprogram (cataloged object) that is used for accessing and possibly modifying data or performing services that are not accessible by Natural statements. Natural APIs refer to Natural, a subcomponent or a subproduct.
The SYSEXT Utility - Natural Application Programming Interfaces documentation covers the following topics:
Application Programming Interfaces - Natural Security documentation
Application Programming Interfaces - Natural SAF Security documentation
SYSAPI - APIs of Natural Add-on Products - Utilities documentation
For each Natural API, the utility SYSEXT provides a functional description, one example program, one category and API-specific keywords.
The following diagram is an overview of the Natural objects and major features SYSEXT provides:
The types of Natural object typically provided for each Natural API are listed in the following section. Additional objects that might exist for a particular API are not covered.
All API-related objects are contained in the library SYSEXT on the system file FNAT.
In the following table, nnnn denotes the 4-digit number to identify the API as well as the corresponding example program and text object.
Object Name | Explanation |
---|---|
USRnnnnN | The API subprogram (cataloged object) that performs the designated function. |
USRnnnnP |
An example program (source object) that can be used to test the effect of the API. The example program invokes the corresponding subprogram USRnnnnN. |
USRnnnnT |
A text object listing a short and a long description, and information on usage, keywords, category and interface versions. You can display a text object by using the line
command |
For some APIs, copycodes are available which provide functions related
to the API. The copycodes are named
USRnnnnX
, where
X
is an identification character (such
as "Z", "Y" etc.).
The SYSEXT utility is invoked by the system command
SYSEXT
which is described by the following syntax
diagram:
SYSEXT |
ALL |
FIRST |
DESCENDING |
||||||
CURRENT |
SECOND
|
ASCENDING
|
The table below gives a description of the parameters:
Parameter | Description |
---|---|
ALL | List all APIs (default). |
CURRENT | List only current APIs, that is all unique APIs and the current version of APIs with interface versions (with keyword +CURRENT-VERSION). See Interface Versions. |
FIRST | Display first menu with product code items (default), see below for an example. |
SECOND | Display second menu with category items, see below for an example. |
ASCENDING | Display APIs in ascending order (default). |
DESCENDING | Display APIs in descending order. |
To invoke SYSEXT
Enter the following system command:
SYSEXT
A menu similar to the example below appears with a list of all available Natural APIs displayed according to the first menu:
07:43:19 ***** NATURAL SYSEXT UTILITY ***** 2010-09-15 User SAG - Menu - Library SYSEXT Cmd Interface Description Prod --- USR*____ _____________________________________________________________ *__ _ USR0010N Get SYSPROF information NAT _ USR0011N Get information on logical file NAT _ USR0020N Read any error message from FNAT or FUSER NAT _ USR0040N Get type of last error NAT _ USR0050N Get SYSPROD information NAT _ USR0060N Copy LFILE definition from FNAT to FUSER NAT _ USR0070P Define editor default profile 'SYSTEM' NAT _ USR0080N Get or set type and name of editor contents NAT _ USR0100N Maintain record length of VSAM datasets NVS _ USR0120N Read Natural short error message NAT _ USR0210N Save, catalog or stow Natural object NAT _ USR0220N Read Natural long error message NAT _ USR0320N Read user short error message from FNAT or FUSER NAT Category .. ______________________________ Keyword .. ____________________ Command ===> Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12--- Help Reset Exit Desc Curr -- - + ++ > Canc |
You can invoke SYSEXT with any parameters, for example to display the second menu at startup:
SYSEXT SECOND
This results in a menu similar to the one below:
07:43:19 ***** NATURAL SYSEXT UTILITY ***** 2010-09-15 User SAG - Menu - Library SYSEXT Cmd Interface Description Category --- USR*____ __________________________________ *_____________________________ _ USR0010N Get SYSPROF information SYSTEM COMMANDS _ USR0011N Get information on logical file SYSTEM FILES _ USR0020N Read any error message from FNAT o ERROR MESSAGES _ USR0040N Get type of last error ERROR HANDLING _ USR0050N Get SYSPROD information SYSTEM COMMANDS _ USR0060N Copy LFILE definition from FNAT to SYSTEM FILES _ USR0070P Define editor default profile 'SYS EDITOR _ USR0080N Get or set type and name of editor EDITOR _ USR0100N Maintain record length of VSAM dat VSAM _ USR0120N Read Natural short error message ERROR MESSAGES _ USR0210N Save, catalog or stow Natural obje NATURAL OBJECTS _ USR0220N Read Natural long error message ERROR MESSAGES _ USR0320N Read user short error message from ERROR MESSAGES Category .. ______________________________ Keyword .. ____________________ Command ===> Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12--- Help Reset Exit Desc Curr -- - + ++ < Canc |
As an alternative, you can invoke SYSEXT without parameters and then adjust the resulting menu, see PF Keys.
To terminate SYSEXT
On the SYSEXT utility menu, press PF3 or PF12.
Or:
In the command line, enter a period (.
) or enter
EXIT
.
This section covers the following topics:
The SYSEXT utility menu provides a list of APIs. For each API, there is an API name (Interface), a description (Description), and, depending on the menu chosen, a classification according to product code (Prod) or category (Category). Except for the leftmost column (Cmd), each column is headed by a selection field that allows you to enter selection criteria.
You can also use the search field Category at the bottom of the menu to search for available categories.
The input field Keywords can either be used as search field to retrieve available keywords, or as selection field to retrieve APIs.
You can also specify selection criteria on multiple selection fields.
For example, you can select in one step APIs beginning with USR4
,
and with keyword PF-KEY
and category NATURAL
ENVIRONMENT
.
A detailed description of all menu elements and their usage is given below:
Element | Explanation | Usage | ||||
---|---|---|---|---|---|---|
Cmd | The input field for a line command to be executed on a text object or an example program: see Line Commands. | Enter a line command, example:
|
||||
Interface | The name of the API subprogram. APIs with interface versions are displayed intensified. | Enter an asterisk (* ) , or a prefix
to be delimited by an asterisk, example:
|
||||
Description | A brief description of the purpose of the API. | Enter a string, example:
|
||||
Prod |
The product code of Natural ( Available product codes: Product codes other than Only visible on the first menu. |
Enter a name, or a prefix to be delimited by an
asterisk (* ), example:
|
||||
Category (selection field) |
The category by which the API is classified according to its functional area or purpose. An API can only have one category. Only visible on the second menu and positioned above the list of APIs. |
Enter a name, or a prefix to be delimited by an
asterisk (* ), example:
|
||||
Category (search field ) |
List all categories. Positioned below the list of APIs. |
See Category Search. | ||||
Keyword | List all keywords or enter a keyword as selection criterion. | See Keyword Search or Keyword Selection. | ||||
Command | Command line to enter utility commands. | Enter a utility command. See Utility Commands. |
Category Search
Enter an asterisk (*
), or a prefix in the category
search field optionally delimited by an asterisk, for example:
N*
As a result, a menu similar to the example below appears:
Search for Categories Mark Category ---- N*____________________________ _ NATURAL ENVIRONMENT _ NATURAL OBJECTS |
To select a specific category as selection criterion, enter any character in the Mark column. As a result, a list of all APIs with this selection criterion is displayed.
Keyword Search
Enter an asterisk (*
), or a prefix delimited by an
asterisk, for example:
PF*
A menu similar to the example below appears with a separate window
displaying keywords starting with PF
.
Search for Keywords Mark Keyword ---- PF*_________________ _ PF-KEY _ PF-KEY LINE |
To select a specific keyword as selection criterion, enter any character in the Mark column. As a result, a list of all APIs with this selection criterion is displayed.
Keyword Selection
Enter a keyword in full, for example:
PF-KEY
As a result, a list of all APIs with keyword PF-KEY
is
displayed.
Note:
A non-trailing asterisk is interpreted literally, for example
entering *LANGUAGE
results in a list of APIs with keyword
*LANGUAGE
.
You can use the following PF keys:
PF Key | Name | Function |
---|---|---|
PF1 | Help | Display context-sensitive help. There is a specific help text for each input field. In other contexts, for example the command line, a general help text is displayed. |
PF2 | Reset | Clear all selection fields and readjust the list of APIs. |
PF3 | Exit | Exit the SYSEXT utility, or the current menu or window. |
PF4 | Asc/Desc | Toggle between ascending (Asc) and descending (Desc) order of APIs. |
PF5 | All/Curr | Toggle between menus displaying all APIs (All) and menus displaying only current APIs (Curr). See Interface Versions. |
PF6 | -- | Scroll to the beginning of the list. |
PF7 | - | Scroll one page up. |
PF8 | + | Scroll one page down. |
PF9 | ++ | Scroll to the end of the list. |
PF10 | < | Shift to first menu. |
PF11 | > | Shift to second menu. |
PF12 | Canc | Exit the SYSEXT utility or the current menu or window. |
Line commands are used to perform object operations. You can enter a
line command in the Cmd column next to the API required.
For a list of valid line commands, enter a question mark (?
) or
press PF1.
The following line commands are available:
Line Command | Function |
---|---|
K
|
List keywords relevant to the specified API. |
T
|
List text object USRnnnnT for a
description of the corresponding API.
The description comprises purpose, function and calling conventions of the API, relevant keywords and its category. |
L
|
List example program USRnnnnP. |
E
|
Edit example program USRnnnnP. |
R
|
Run example program USRnnnnP. |
X
|
Execute example program USRnnnnP. |
.
|
Exit the SYSEXT utility. |
This section covers the following utility commands to be entered in the command line:
EXIT
Exit the SYSEXT utility.
REFRESH
Update API information using data from the objects contained in the
current library SYSEXT. The REFRESH
command is only
required if an API description or a keyword has been modified or if a text
object has been added or removed.
Upon successful completion, there is a confirmation that the text modules EXT-XML1 and EXT-XML2 have been generated in library SYSEXT.
Note:
Do not modify the source objects EXT-XML1 and EXT-XML2.
They are required for configuring the SYSEXT utility and intended for Software
AG internal use only.
Interface versions can be seen as a collection of APIs with (almost) the same functionality but with differently extended parameter specifications. Thus, they cover a development cycle to be kept explicit for sake of compatibility (of later versions with earlier versions).
If an API has interface versions, they are displayed in the
corresponding text object USRnnnnT. Interface
versions are ordered within a list according to the version they belong to. The
rightmost element belongs to the current version. This status is expressed by
the reserved keyword +CURRENT-VERSION
. All other elements belong
to a previous version and are marked with the reserved keyword
+PREVIOUS-VERSION
. APIs without interface versions are called
unique.
APIs with interface versions are displayed intensified on the menu.
The list of all current APIs (see
PF5) consists
of all unique APIs and the current version of APIs with interface versions
(with keyword +CURRENT-VERSION
).
Reserved keywords refer to meta information on APIs, for example the
Natural version in which an API has been added. Reserved keywords always start
with a plus sign (+
). See the table below for a description:
Reserved Keyword | Description |
---|---|
+CURRENT-VERSION | The current version of an API with interface versions (see Interface Versions). |
+PREVIOUS-VERSION | A previous version of an API with interface versions (see Interface Versions). |
+NEW-PROD-version | An API that has been added to a specific product
in a specific version. For example, +NEW-NAT-4.2.7 refers
to an API that has been added to the product Natural in version 4.2.7 .
|
+MOD-PROD-version | An API that belongs to a specific product and has
been modified in a specific version. For example, +MOD-NAT-8.2.1 refers
to an API that belongs to product Natural and has been modified in version
8.2.1 .
|
If you want to use a Natural API contained in the system library SYSEXT, perform one of the following steps:
Define the system library SYSEXT in the system file FNAT as a steplib library for the user library that contains the Natural objects that use this API. Thus, no API-specific actions are required when upgrading your Natural version.
Copy the required API to the system library SYSTEM in the system file FNAT. Thus, you only need to check a single library for APIs when upgrading your Natural version.
Copy the required API to the system library SYSTEM in the system file FUSER (not recommended).
Copy the required API to the user library (or one of its steplibs) in the system file FUSER which contains the Natural objects that use this API (not recommended).
An API can only be used in the Natural version with which it is delivered. It is strongly recommended to store the APIs only in the FNAT system file. This will ensure that the right version is always executed.
To make use of an interface
In the calling program, use the DEFINE DATA
statement to
specify the parameters listed in the text object
USRnnnnT
of that API. In the example
program USRnnnnP
, the parameters are
defined within the DEFINE DATA
LOCAL
statement. Alternatively, you can specify the
parameters outside the calling program in a separate LDA (Local Data Area) or
PDA (Parameter Data Area), with a DEFINE DATA LOCAL USING
statement referencing that data area.
Enter the following statement:
CALLNAT 'USRnnnnN' parameters
For further information, see the CALLNAT statement in the Statements documentation.
Note:
Non-standard usage is always documented in the respective text
object USRnnnnT
.
If you want to use a Natural copycode contained in the system library SYSEXT, perform the following step:
Copy the required copycode to the user library in the system file FUSER which contains the Natural objects that use this copycode.
To make use of a copycode
In the calling program, use the INCLUDE
statement to specify
the parameters listed in the text object
USRnnnnT
of that API or in the copycode
itself. In the example program
USRnnnnP
, the parameters are defined
within the DEFINE DATA
LOCAL
statement. Alternatively, you can specify the
parameters outside the calling program in a separate LDA (Local Data Area) or
PDA (Parameter Data Area), with a DEFINE DATA LOCAL USING
statement referencing that data area.
Some copycodes require additional data definitions. These are
described in the text object USRnnnnT
of the API and in the copycode itself.
Enter the following statement:
INCLUDE USRnnnnX 'parameter'...
For further information, see the INCLUDE statement in the Statements documentation.
Note:
Non-standard usage is always documented in the respective text object
USRnnnnT
.