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 specific to Natural, a subcomponent or a subproduct. The purpose of a Natural API is to retrieve or modify information or use services that are not accessible by Natural statements.
The SYSEXT Utility - Natural Application Programming Interfaces documentation covers the following topics:
Application Programming Interfaces - Natural Security documentation
For each Natural API, the utility SYSEXT provides a functional description, one example program and API-specific keywords.
The following diagram is an overview of the Natural objects and major features SYSEXT provides to test and implement an API:
The types of Natural object typically provided for each Natural API are listed in the following section. The section does not list additional objects that may be required for particular APIs.
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 assigned to the API. All API objects that relate to one another have identical numbers.
| 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 that contains a description of the corresponding API. The description comprises purpose, function and calling conventions of the API and relevant keywords. You can display a text object by using the line
command You can search for a text object by specifying a keyword as described in Keyword Search in Performing SYSEXT Utility Functions. |
This section provides instructions for invoking and terminating the SYSEXT utility.
To invoke SYSEXT
Enter the following system command:
SYSEXT
A SYSEXT utility screen similar to the example below appears with a list of all available Natural APIs:
15:07:28 ***** NATURAL SYSEXT UTILITY ***** 2006-01-26
User SAG - Menu - Library SYSEXT
Cmd Source Interface Comment Prod
_ USR0010P USR0010N Get 'SYSPROF' Information NAT
_ USR0011P USR0011N Information about logical file NAT
_ USR0020P USR0020N Read any error text from FNAT / FUSER NAT
_ USR0040P USR0040N Get type of last error NAT
_ USR0050P USR0050N Get 'SYSPROD' Information NAT
_ USR0060P USR0060N Copy LFILE definition from 'FNAT' to 'FUSER' NAT
_ USR0080P USR0080N Handle Type/Name of Editor Contents NAT
_ USR0120P USR0120N Read NATURAL Short Error Message NAT
_ USR0210P USR0210N Save, cat or stow NATURAL object NAT
_ USR0220P USR0220N Read NATURAL Long Error Message NAT
_ USR0221P USR0221N Read NATURAL Long Error Message NAT
_ USR0320P USR0320N Read User Short Error Message from FNAT or FUSER NAT
_ USR0330P USR0330N Read NATURAL Object Directory NAT
_ USR0360P USR0360N Modify User Short Error Message NAT
Keyword .. ________________
Command ===>
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
Help Exit -- + Canc
|
The list is sorted by the names of the example programs (USRnnnnP). If required, press PF8 to scroll down one page in the list or PF7 to go to the beginning of the list.
To terminate SYSEXT
On the SYSEXT utility screen, press PF3 or PF12.
Or:
In the Command line, enter a period
(.) or enter EXIT.
The field and columns contained on the SYSEXT utility screen are explained in the following table:
| Column | Explanation |
|---|---|
| Cmd | The input field for a line command to be executed on a text object or an example program: see Line Commands in Performing SYSEXT Utility Functions. |
| Source | The name of the example program (source object USRnnnnP) that can be used to invoke the API. |
| Interface | The name of the API subprogram USRnnnnN. |
| Comment | A brief description of the purpose of the API. |
| Prod |
The product code of Natural ( For example: |
| Keyword | The input field for a keyword relevant to an API: see Keyword Search in Performing SYSEXT Utility Functions. |
The SYSEXT utility functions can be used to perform operations on the text objects and example programs referenced in the API list on the SYSEXT utility screen. In addition, you can use the keyword search function to shorten the list of APIs or list all keywords available for the APIs.
The section below covers the following topics:
Line commands are used to perform object operations. You enter a line
command in the Cmd column next to the API required. For a
list of valid line commands, enter a question mark (?) in this
column.
The following line commands are available on the SYSEXT utility screen:
| Line Command | Function |
|---|---|
E
|
Edit example program USRnnnnP. |
L
|
List example program USRnnnnP. |
R
|
Run example program USRnnnnP. |
X
|
Execute example program USRnnnnP. |
D
|
List text object USRnnnnT for a description of the corresponding API. The description comprises purpose, function and calling conventions of the API and keywords that are relevant to the API. |
K
|
List keywords relevant to the specified API. |
.
|
Terminate the SYSEXT utility. |
Keywords help you find the Natural APIs relevant to your current task. You can use the keyword search function to list APIs by keyword or list the keywords relevant to a specific API.
To list APIs by keyword
Choose any of the following methods:
Enter a single keyword:
On the SYSEXT utility screen, in the Keyword field, type in a keyword and press ENTER.
A list of all APIs to which the specified keyword applies appears.
Select a single keyword from a list of valid keywords:
On the SYSEXT utility screen, in the
Keyword field, enter an asterisk (*) and
press ENTER.
The List Keywords window with a list of all keywords available for all APIs appears as shown in the example below.
If required, press PF8 to scroll down the list of keywords or press PF7 to go to the beginning of the list.
In the M column, next to the desired keyword, type in any character and press ENTER.
Or: In the Direct field, enter the desired keyword and press ENTER.
A list of all APIs to which the specified keyword applies appears.
Select multiple keywords from a list of valid keywords:
On the SYSEXT utility screen, in the
Keyword field, enter an asterisk (*) and
press ENTER.
The List Keywords window with a list of all keywords available for all APIs appears as shown in the example below.
If required, press PF8 to scroll down the list of keywords or press PF7 to go to the beginning of the list.
In the M
column, next to the desired keywords, type in an asterisk (*) and
press ENTER.
The Keyword window appears with a list of
all APIs to which the first keyword selected applies (here:
*LANGUAGE) as shown in the example below:
11:08:58 ***** NATURAL SYSEXT UTILITY ***** 2005-11-10
User SAG - Menu - Library SYSEXT
Cm +--------List Keywords---------+ +--------Keyword *LANGUAGE--------+ Prod
_ ! ! ! ! NAT
_ ! M Keyword ! ! Object ! NAT
_ ! _ *DATX ! ! USR0020P ! NAT
_ ! _ *ERROR-NR ! ! USR0120P ! NAT
_ ! _ *ERROR-TA ! ! USR0320P ! NAT
_ ! * *LANGUAGE ! ! USR1027P ! NAT
_ ! _ *LEVEL ! ! USR1030P ! NAT
_ ! _ *STEPLIB ! ! USR2034P ! NAT
_ ! * *TIMESTMP ! ! USR3320P ! NVS
_ ! _ *TIMX ! ! ! NAT
_ ! _ ABEND ! ! ! NAT
_ ! ! ! ! NAT
_ ! Direct ... ________________ ! ! ! R NAT
_ ! ! ! ! NAT
+------------------------------+ +---------------------------------+
Keyword .. *_______________
Command ===>
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
Help Exit -- + Canc
|
Press ENTER to open the Keyword
window for the next keyword selected (here: *TIMESTMP).
Press ENTER or PF3 to return to the List Keywords window.
Press PF3 to leave all windows and return to the SYSEXT utility screen.
To list keywords relevant to a specific API
Next to the API required, enter the line command K. The
Keywords window appears for the specified API with a list
of all keywords that are relevant to this API as shown in the example below:
11:24:27 ***** NATURAL SYSEXT UTILITY ***** 2005-11-10
User SAG - Menu - Library SYSEXT
Cmd Source Interface Comment Prod
K USR0010P USR0010 +--Keywords for USR0010P--+ NAT
_ USR0011P USR0011 ! ! file NAT
_ USR0020P USR0020 ! DBID ! FNAT / FUSER NAT
_ USR0040P USR0040 ! ENVIRONMENT ! NAT
_ USR0050P USR0050 ! FILE ! NAT
_ USR0060P USR0060 ! FNAT ! m 'FNAT' to 'FUSER' NAT
_ USR0070P USR0070 ! FNR ! YSTEM' NAT
_ USR0080P USR0080 ! FUSER ! r Contents NAT
_ USR0100P USR0100 ! SYSPROF ! NVS
_ USR0120P USR0120 ! ! Message NAT
_ USR0210P USR0210 ! ! object NAT
_ USR0220P USR0220 ! ! essage NAT
_ USR0320P USR0320 +-------------------------+ sage from FNAT or FUSER NAT
_ USR0330P USR0330N Read Natural Object Directory NAT
Keyword .. ________________
Command ===>
Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---;
|
If required, press PF8 to scroll down one page in the list. Press PF7 to go to the beginning of the list.
If you want to use a Natural API contained in the SYSEXT system library, perform one of the following steps:
Define the SYSEXT system library in the FNAT system file as a steplib library for the user library which 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 system library in the FNAT system file. Thus, you only need to check a single library for APIs when upgrading your Natural version.
Copy the required API to the SYSTEM library in the FUSER system file (not recommended).
Copy the required API to the user library (or one of its steplibs) in the FUSER system file 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 cannot be executed in any other Natural version. Therefore, it is strongly recommended that APIs are stored only in the FNAT system file.
