Application Programming Interface

#### Search Results

Search

# Application Programming Interface

The programs described in this document can be used in Natural applications (or in Open NSPF routines) to access Natural ISPF internal information.

All programs and required Natural ISPF modules are loaded into the Exit Library and into the library `SYSTEM`. If you wish to use the API programs, it is strongly recommended that you define either `SYSTEM` or `SYSISPE` as `STEBLIB` for your application.

This document covers the following topics:

- ISP-U000 - Current Session Program

- ISP-U001 - Access Shortlibs Program

- ISP-U002 - Retrieve Error Texts Program

- ISP-U003 - Read Data from Edit Session Program

- ISP-U004 - Pass Command Script Program

- ISP-U005 - Check for Natural Member Versions Program

- ISP-U006 - Set Source Area Attributes Program

- ISP-U007 - Check User Authorization Program

- ISP-U008 - Current Session Program Including Global Data

- ISP-U009 – Current Session Program / Previous Session Program

## ISP-U000 - Current Session Program

This program is supplied in object form only. It is a Natural subprogram which returns information about the current Natural ISPF session and can be called from user programs outside Natural ISPF.

The following parameters must be defined:

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#OBJECT` | (A2) | O | Contains 2-character abbreviation of the object type. For a list of possible values, see the Table of Exits and Object Abbreviations in section User Exits in the Natural ISPF Administration Guide.
`#FUNCTION` | (A2) | O | Contains 2-character abbreviation of the function currently executed.
`#SES-DATA` | (A253) | O | Contains all parameters; must be redefined according to object type. A special local data area is delivered in source form for this redefinition.

### Example

The following example is a short Natural macro object which users can call using the `COPY MACRO` command from an edit session. It generates a program header and uses program `ISP-U000` to obtain the name and library of the program being edited:

      § *
      § * MACRO GENERATES A STANDARD PROGRAM HEADER FOR THE PROGRAM
      § * BEING CURRENTLY EDITED
      § *
      § DEFINE DATA
      § LOCAL USING ISPN---L  /* Redefinition of Natural data
      § LOCAL
      § 1 #OBJECT (A2)
      § 1 #FUNCTION(A2)
      § 1 #DATA (A253)
      § 1 #PROGRAM (A8)
      § 1 #TEXT (A50/5)
      § 1 #I (N2)
      § END-DEFINE
      § *
      § * GET NATURAL SESSION DATA
      § *
      § CALLNAT 'ISP-U000' #OBJECT #FUNCTION #DATA
      § MOVE #DATA TO #SES-DATA-N          /* Move to redefinition
      § MOVE #MEMBER TO #PROGRAM
      § SET KEY PF3
      § SET CONTROL 'WL70C12B005/005F'
      § INPUT (AD=MIL'_')
      § WITH TEXT '----- PROGRAM HEADING INFORMATION -------------'
      § 'PROGRAM:' #PROGRAM (AD=OI)
      § 'LIBRARY:' #LIBRARY (AD=OI)
      § / 'PURPOSE:' #TEXT (1)
      § / ' ' #TEXT (2)
      § / ' ' #TEXT (3)
      § / ' ' #TEXT (4)
      § / ' ' #TEXT (5)
      § IF #TEXT(1) = ' '
      § REINPUT WITH TEXT 'PURPOSE IS REQUIRED'
      § END-IF
      ***********************************************************************
      * PROGRAM: §#PROGRAM DATE CREATED: §*DATD BY: §*USER
      * ---------------------------------------------------------------------
      * PURPOSE:
      § FOR #I = 1 TO 5
      § IF #TEXT(#I) NE ' '
      * §#TEXT(#I)
      § END-IF
      § END-FOR
      * ---------------------------------------------------------------------
      * PROGRAM HISTORY
      * DATE USER-ID REF-NO DESCRIPTION
       ***********************************************************************
      *

The following figure shows the result of the `INPUT` statement in the macro when the program is invoked from an edit session with program `NEWPROG` in library `NSPFWORK`:

      EDIT-NAT:NSPFWORK(NEWPROG)-Program->Struct-Free-29K - >>> Versioning is invoked
       COMMAND===> COPY MAC MAC-HEAD                                  SCROLL===> CSR
      ****** ****************************** top of data *****************************
      ****** **************************** bottom of data ****************************

           +-------------------------------------------------------------------+
           ! ----- PROGRAM HEADING INFORMATION -------------                   !
           ! PROGRAM: NEWPROG  LIBRARY: NSPFWORK                               !
           ! PURPOSE: This program demonstrates something _____________        !
           !          _________________________________________________        !
           !          _________________________________________________        !
           !          _________________________________________________        !
           !          _________________________________________________        !
           !                                                                   !
           ! Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10- !
           !       Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  !
           +-------------------------------------------------------------------+

      Enter-PF1---PF2---PF3---PF4---PF5---PF6---PF7---PF8---PF9---PF10--PF11--PF12---
            Help  Split End   Suspe Rfind Rchan Up    Down  Swap  Left  Right Curso

Another useful example called `COPYSYS` can be found in the Example Library. This program copies a member which is edited to the library `SYSLIB`.

## ISP-U001 - Access Shortlibs Program

This program allows user programs to access short library names defined in Natural ISPF either in the user profile or in the global shortlib table. If an entry is found, the data set name and volser of the data set is returned.

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#IN-SHORT` | (A2) | I | 2-byte library abbreviation.
`#OUT-DSN` | (A44) | O | Data set name, if given abbreviation was found.
`#OUT-VOLSER` | (A6) | O | Volser, if defined in profile.

## ISP-U002 - Retrieve Error Texts Program

This program can be used to retrieve error texts from the Natural ISPF Error Message Library `SYSISPSx` (where x is the current language code). If a text is not found for the current language code, the English text is returned. Parameters can be replaced in the error text.

This program can only be used by Open NSPF programs, which are executed from `SYSLIB`. This program will not work if invoked from any user application.

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#ERR-NUMBER` | (N4) | I | Error number to be retrieved.
`#ERR-TEXT` | (A75) | O | Text, including substituted parameters.
`#ERR-PARM` | (A75) | I | Parameters separated by (;). Formal parameters in the text must be specified as `:n:`, where `n` is the number of the parameter.

Note
Error messages 9000 - 9999 are reserved for use by your site.

## ISP-U003 - Read Data from Edit Session Program

This program can be used to read data from an edit session. When using this program, you must use the `ISP-U03A` data area which contains the following fields:

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#LINES` | (A132/20) | O | Data lines from the Editor session, a maximum of 20 lines can be read in one call.
`#ED-SESNUM` | (B2) | I | Editor session number.
`#ERROR-NUMBER` | (N4) | O | Error number, `0` if function was executed correctly.
`#LINES-READ` | (N2) | O | Number of lines returned in field `#LINES`.
`#LINES-TO-READ` | (N2) | I/O | Number of lines to read in 1 call
`#LINE-LENGTH` | (N4) | O | Length of the lines.
`#ED-NUM` | (N6) | W | Do not modify between calls.
`#EOF` | (L) | O | True if the last lines have been read.
`#TRACE` | (L) | O | If true, the number of lines, the information about the last line and the first 60 characters of each line read are displayed.

### Example:

    DEFINE DATA
    LOCAL USING ISP-U03A
    LOCAL
    1 #I    (N2)
    END-DEFINE
    INPUT #ED-SESNUM
    *
    MOVE 20 TO   #LINES-TO-READ
    *
    WRITE 'user processing of a macro result' //
    *
    REPEAT
      CALLNAT 'ISP-U003' #READ-PARM
      IF #ERROR-NUMBER NE 0
        WRITE '=' #ERROR-NUMBER
        ESCAPE BOTTOM
      END-IF
      FOR #I = 1 TO #LINES-READ
        PERFORM LINE-PROCESSING
      END-FOR
      IF #EOF
        ESCAPE BOTTOM
      END-IF
    END-REPEAT
    *
    DEFINE SUBROUTINE LINE-PROCESSING
    PRINT  #LINES(#I)
    END-SUBROUTINE
    END

## ISP-U004 - Pass Command Script Program

This subprogram can be used to pass a command script (that is, a sequence of Natural ISPF commands) to Natural ISPF and to execute it when Natural ISPF is invoked next time. See also member `ISP-COAP` in the example library.

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#IN-COMMANDS` | (A50/10) | I | Command lines to be processed.
`#IN-LINES` | (N2) | I | Number of lines to be processed in `IN-COMMANDS`.
`#COMMAND-POS` | (A1) |  | For future use.
`#FUNCTION` | (A1) |  | For future use.
`#RC` |  | O | Return code: 0 - Processing terminated ok. 1 - Natural ISPF is not active. 2 - Processing terminated with error.

## ISP-U005 - Check for Natural Member Versions Program

Subprogram checks whether versions (update decks) for a Natural member exist.

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#IN-LIBRARY` | (A8) | I | Natural library name.
`#IN-MEMBER` | (A8) | I | Natural member name.
`#RC` | (N4) | O | Return code: `0` - Processing terminated ok.
`#OUT-VERSION` | (L) | O | `TRUE` Versions for this member exist.
`#GEN-VERSION` | (L) | O | `FALSE` Natural ISPF versioning is not active in this environment.

## ISP-U006 - Set Source Area Attributes Program

Subprogram sets source area attributes and is used in macro processing.

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#IN-MEMBER` | (A8) | I | Member name to be set.
`#IN-TYPE` | (A1) | I | Natural object type to be set.
`#IN-MODE` | (A1) | I | Programming mode (`S/R`) to be set.

## ISP-U007 - Check User Authorization Program

This subprogram checks whether the current user is authorized to use Natural ISPF or certain parts of its functionality.

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#IN-OBJECT` | (A2) | I | 2-character code of Natural ISPF object being checked (leave blank to check if user is authorized to access any object).
`#IN-FUNCTION` | (A2) | I | 2-character code of Natural ISPF object being checked (leave blank to check if user is authorized to use any function valid for a specific object; irrelevant if `IN-OBJECT` is blank).
`#RC` | (N4) | O | Return code: `0` - User is authorized. `-1` - User is not authorized. `>0` - "Error in execution". Use `USR0320N` to retrieve error text from library `SYSISP1`. `= -NNNN` - Natural runtime error `NNNN` has occurred during execution. Use `USR0120N` to retrieve error text.

## ISP-U008 - Current Session Program Including Global Data

This program is supplied in object form only. It is a Natural subprogram which returns information about the current Natural ISPF session and can be called from user programs outside Natural ISPF. It works like `ISP-U000` but includes global data

The following parameters must be defined:

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#OBJECT` | (A2) | O | Contains 2-character abbreviation of the object type. For a list of possible values, see the Table of Exits and Object Abbreviations in the section User Exits in the Natural ISPF Administration Guide.
`#FUNCTION` | (A2) | O | Contains 2-character abbreviation of the function currently being executed.
`#CURR-SES-NUM` | (N2) | O | Contains session number of SAG edit session.
`#L-COMMAND` | (A50) | O | Contains command line to be interpreted.
`#MACRO-CHAR` | (A1) | O | Contains character which will be interpreted as macro character.
`#CMD-DEL` | (A1) | O | Contains command delimiter character for command line.
`#SES-DATA` | (A253) | O | Contains all parameters; must be redefined according to object type. A special local data area is delivered in source form for this redefinition

## ISP-U009 – Current Session Program / Previous Session Program

This program is supplied in object form only. It is a Natural subprogram which returns information about the current Natural ISPF session and can be called from user programs outside Natural ISPF. It works in the same way as `ISP-U000` except when executing a Natural program. In this case, the data of the previous session is returned.

The following parameters must be defined:

Parameter | Format | Type | Meaning
--- | --- | --- | ---
`#OBJECT` | (A2) | O | Contains 2-character abbreviation of the object type. For a list of possible values, see the Table of Exits and Object Abbreviations in section User Exits in the Natural ISPF Administration Guide.
`#FUNCTION` | (A2) | O | Contains 2-character abbreviation of the function currently executed.
`#SES-DATA` | (A253) | O | Contains all parameters; must be redefined according to object type. A special local data area is delivered in source form for this redefinition.

### On this page

- ISP-U000 - Current Session Program
- ISP-U001 - Access Shortlibs Program
- ISP-U002 - Retrieve Error Texts Program
- ISP-U003 - Read Data from Edit Session Program
- ISP-U004 - Pass Command Script Program
- ISP-U005 - Check for Natural Member Versions Program
- ISP-U006 - Set Source Area Attributes Program
- ISP-U007 - Check User Authorization Program
- ISP-U008 - Current Session Program Including Global Data
- ISP-U009 – Current Session Program / Previous Session Program