
	Version 6.3.12 for OpenVMS	SEARCH CONTENTS \| PDF BOOKS \| HOME UP PREV NEXT

— Tools and Utilities —

SYSEXT Utility - Natural Application Programming Interfaces

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:

Introduction to SYSEXT
Invoking and Terminating SYSEXT
SYSEXT Utility Screen
Performing SYSEXT Utility Functions
Using a Natural API

Introduction to SYSEXT

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:

graphics/sysext_open_system.png

Objects Provided for Natural APIs

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.

Object Name	Explanation
USR`nnnn`N	The API subprogram (cataloged object) that performs the designated function.
USR`nnnn`P	An example program (source object) that can be used to test the effect of the API. The example program invokes the corresponding subprogram USR`nnnn`N.
USR`nnnn`T	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 `D` as described in Line Commands in Performing SYSEXT Utility Functions. You can search for a text object by specifying a keyword as described in Keyword Search in Performing SYSEXT Utility Functions.

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 D as described in Line Commands in Performing SYSEXT Utility Functions.

You can search for a text object by specifying a keyword as described in Keyword Search in Performing SYSEXT Utility Functions.

Invoking and Terminating SYSEXT

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.

SYSEXT Utility Screen

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 USR`nnnn`P) that can be used to invoke the API.
Interface	The name of the API subprogram USR`nnnn`N.
Comment	A brief description of the purpose of the API.
Prod	The product code of Natural (`NAT`) or a Natural add-on product affected by the API. For example: `NAT` = Natural, `NDB` = Natural for DB2, `NVS` = Natural for VSAM, `PRD` = Predict, `RPC` = Natural Remote Procedure Call.
Keyword	The input field for a keyword relevant to an API: see Keyword Search in Performing SYSEXT Utility Functions.

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
Keyword Search

Line Commands

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 USR`nnnn`P.
`L`	List example program USR`nnnn`P.
`R`	Run example program USR`nnnn`P.
`X`	Execute example program USR`nnnn`P.
`D`	List text object USR`nnnn`T 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.

Keyword Search

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:
1. 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.
2. 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.

Using a Natural API

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.

SEARCH CONTENTS | PDF BOOKS | HOME UP PREV NEXT